Saltar al contenido principal

Control de reSpeaker Clip con Python

Introducción​

pir

El SDK de reSpeaker Clip proporciona una interfaz de Python para comunicarse con dispositivos reSpeaker Clip mediante Bluetooth Low Energy (BLE) o WiFi.

Con este SDK puedes:

  • Conectarte a un reSpeaker Clip
  • Leer información del dispositivo
  • Configurar parámetros de grabación
  • Iniciar y detener grabaciones
  • Añadir marcadores
  • Sincronizar grabaciones
  • Controlar el dispositivo usando Python
  • Usar herramientas de línea de comandos listas para usar
  • Acceder al dispositivo a través de una interfaz web

Instalación​

Requisitos​

  • Python 3.10+
  • Adaptador Bluetooth (modo BLE)
  • Adaptador WiFi (modo WiFi)

Clonar el repositorio​

git clone <repository-url>

cd applications/clip/tests

Instalar dependencias​

pip install -r requirements.txt

Estructura del proyecto​

applications/clip/tests/

├── clip/
│   ├── client.py
│   ├── commands.py
│   ├── transfer.py
│   ├── codec.py
│   ├── wifi.py
│   ├── progress.py
│   ├── utils.py
│   └── exceptions.py

├── tools/
│   ├── clip-cli.py
│   ├── clip-web.py
│   ├── record.py
│   ├── sync.py
│   ├── udp_sync.py
│   ├── ble_terminal.py
│   └── decode_opus.py

├── requirements.txt
├── README.md
└── EXAMPLES.md

Módulos del SDK​

MóduloDescripción
client.pyComunicación con el dispositivo BLE
commands.pyComandos AT de alto nivel
transfer.pySincronización de archivos
codec.pyCodificación/decodificación de audio
wifi.pyTransporte WiFi
progress.pyVisualización de progreso
utils.pyFunciones auxiliares
exceptions.pyClases de excepción

Primeros pasos​

Conectar al dispositivo​

import asyncio
from clip import ClipDevice, ClipCommands

async def main():

    async with ClipDevice() as device:

        cmds = ClipCommands(device)

        state = await cmds.get_state()

        print(state.battery)

asyncio.run(main())

El SDK busca automáticamente dispositivos cercanos con el nombre:

Clip XXXX

Conectarse a un dispositivo específico​

device = ClipDevice(
    address="AA:BB:CC:DD:EE:FF"
)

await device.connect()

Información del dispositivo​

Leer versión de firmware​

version = await cmds.get_version()

print(version.firmware)
print(version.hardware)

Leer estado del dispositivo​

state = await cmds.get_state()

print(state.state)
print(state.battery)
print(state.mode)

Leer hora del dispositivo​

timestamp = await cmds.get_time()

Establecer hora del dispositivo​

import time

await cmds.set_time(
    int(time.time())
)

Grabación de audio​

Iniciar grabación​

session_id = await cmds.start_recording("normal")

Detener grabación​

await cmds.stop_recording()

Pausar grabación​

await cmds.pause_recording()

Reanudar grabación​

await cmds.resume_recording()

Añadir marcador​

bookmark = await cmds.add_bookmark()

print(bookmark.offset)

Ejemplo de sesión de grabación​

session = await cmds.start_recording("normal")

await asyncio.sleep(10)

await cmds.stop_recording()

Sincronización de archivos​

Listar sesiones​

sessions = await cmds.list_sessions()

for s in sessions:
    print(s.id)

Sincronizar una sesión (BLE)​

from clip import SessionSync

session_id = "20260326120000"  # obtained from cmds.list_sessions()

sync = SessionSync(device)

await sync.sync(
    session_id,
    Path("recordings")
)

Reanudar descarga interrumpida​

session_id = "20260326120000"

await sync.sync(
    session_id,
    Path("recordings"),
    start_file="0015.opus"
)

Mantener archivos en el dispositivo​

session_id = "20260326120000"

await sync.sync(
    session_id,
    Path("recordings"),
    delete_after=False
)

Gestión de configuración​

Establecer parámetros​

await cmds.set_mode("enhanced")

await cmds.set_bitrate(32000)

await cmds.set_complexity(10)

await cmds.set_noise_suppression(30)

Leer parámetros​

mode = await cmds.get_mode()

bitrate = await cmds.get_bitrate()

Configuración por lotes​

await cmds.set_config_dict({

    "mode":"enhanced",

    "bitrate":32000,

    "complexity":10

})

Comunicación WiFi​

El reSpeaker Clip puede comunicarse por WiFi usando UDP.

Configuración predeterminada:

ParámetroValor
SSIDClipAP_XXXX
Password12345678
Port8089

Conectar​

from clip import WiFiDevice

async with WiFiDevice(
    "192.168.4.1",
    8089
) as device:

    await device.send_command("AT+GSTAT")

Sincronizar por WiFi​

from clip import WiFiSync

session_id = "20260326120000"

sync = WiFiSync(
    "192.168.4.1",
    8089
)

sync.connect()

sync.download_session(
    session_id,
    Path("recordings")
)

sync.disconnect()

Herramientas de línea de comandos​

El SDK incluye varias utilidades listas para usar.

clip-cli​

CLI de propósito general.

clip-cli status

clip-cli version

clip-cli list

clip-cli record --duration 60

clip-cli sync --session 20260326120000

clip-cli config get

clip-cli bookmark

clip-cli terminal

record.py​

Graba audio automáticamente y lo sincroniza.

python tools/record.py

python tools/record.py --duration 60

python tools/record.py --mode enhanced

sync.py​

Sincroniza grabaciones mediante BLE.

python tools/sync.py

python tools/sync.py --all-sessions

udp_sync.py​

Sincroniza grabaciones mediante WiFi.

python tools/udp_sync.py

python tools/udp_sync.py --session 20260326120000

ble_terminal.py​

Terminal interactivo de comandos AT.

python tools/ble_terminal.py

decode_opus.py​

Convierte grabaciones Opus a WAV.

python tools/decode_opus.py input.opus output.wav

Interfaz web​

Inicia la aplicación web integrada.

Modo BLE:

python tools/clip-web.py

Modo WiFi:

python tools/clip-web.py --transport wifi

Luego abre:

http://localhost:5000

Funciones​

  • Estado del dispositivo
  • Control de grabación
  • Gestión de sesiones
  • Visualización de audio
  • Editor de configuración
  • Progreso de sincronización

REST API​

MétodoEndpoint
GET/api/status
GET/api/version
GET/api/sessions
POST/api/record/start
POST/api/record/stop
POST/api/record/bookmark
POST/api/sync/{id}
DELETE/api/sessions/{id}
GET/api/config
PUT/api/config
WS/ws

Gestión de errores​

from clip import (
    ConnectionError,
    TimeoutError,
    CommandError
)

try:

    async with ClipDevice() as device:

        ...

except ConnectionError:

    ...

except TimeoutError:

    ...

except CommandError:

    ...

Ejemplo completo​

Este ejemplo demuestra un flujo de trabajo típico:

  1. Conectarse al dispositivo
  2. Comprobar el nivel de batería
  3. Configurar parámetros de grabación
  4. Iniciar la grabación
  5. Añadir marcadores
  6. Detener la grabación
  7. Sincronizar la sesión grabada
import asyncio
from pathlib import Path
from clip import ClipDevice, ClipCommands, SessionSync

async def record_and_sync():
    async with ClipDevice() as device:
        cmds = ClipCommands(device)

        state = await cmds.get_state()
        print(f"Battery: {state.battery}%")

        await cmds.set_config_dict({
            "mode": "enhanced",
            "bitrate": 32000,
            "complexity": 10
        })

        session_id = await cmds.start_recording("normal")
        print(f"Recording started: {session_id}")

        await asyncio.sleep(10)

        await cmds.add_bookmark()
        print("Bookmark added")

        await asyncio.sleep(5)

        await cmds.stop_recording()
        print("Recording stopped")

        sync = SessionSync(device)
        await sync.sync(session_id, Path("recordings"))
        print(f"Session {session_id} synchronized")

asyncio.run(record_and_sync())

Referencia de la API​

ClipDevice​

Propósito: comunicación con el dispositivo BLE y gestión de la conexión.

class ClipDevice:
    def __init__(self, address: str = None) -> None
    async def connect() -> None
    async def disconnect() -> None
    async def __aenter__() -> ClipDevice
    async def __aexit__(...) -> None

ClipCommands​

Propósito: comandos AT de alto nivel para el control del dispositivo.

class ClipCommands:
    def __init__(self, device: ClipDevice) -> None
    async def get_state() -> DeviceState
    async def get_version() -> Version
    async def get_time() -> int
    async def set_time(timestamp: int) -> None
    async def start_recording(mode: str) -> str
    async def stop_recording() -> None
    async def pause_recording() -> None
    async def resume_recording() -> None
    async def add_bookmark() -> Bookmark
    async def list_sessions() -> list[Session]
    async def set_mode(mode: str) -> None
    async def get_mode() -> str
    async def set_bitrate(bitrate: int) -> None
    async def get_bitrate() -> int
    async def set_complexity(level: int) -> None
    async def set_noise_suppression(level: int) -> None
    async def set_config_dict(config: dict) -> None

SessionSync​

Propósito: sincronización de archivos mediante BLE.

class SessionSync:
    def __init__(self, device: ClipDevice) -> None
    async def sync(session_id: str, path: Path, delete_after: bool = True, start_file: str = None) -> None

WiFiDevice​

Propósito: capa de transporte WiFi usando UDP.

class WiFiDevice:
    def __init__(self, host: str, port: int) -> None
    async def connect() -> None
    async def disconnect() -> None
    async def send_command(cmd: str) -> str
    async def __aenter__() -> WiFiDevice
    async def __aexit__(...) -> None

WiFiSync​

Propósito: sincronización de archivos por WiFi.

class WiFiSync:
    def __init__(self, host: str, port: int) -> None
    def connect() -> None
    def disconnect() -> None
    def download_session(session_id: str, path: Path) -> None

Excepciones​

ExcepciónDescripción
ClipErrorExcepción base para todos los errores
ConnectionErrorFallo de conexión BLE/WiFi
TimeoutErrorTiempo de espera de comando agotado
CommandErrorComando AT no válido o fallido

Soporte técnico y debate sobre el producto​

Gracias por elegir nuestros productos. Estamos aquí para ofrecerte diferentes tipos de soporte y garantizar que tu experiencia con nuestros productos sea lo más fluida posible. Ofrecemos varios canales de comunicación para adaptarnos a distintas preferencias y necesidades.

Loading Comments...