mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
hehaijunandhenry
141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# 📡 Canal MQTT
|
|
|
|
O PicoClaw suporta qualquer cliente MQTT como canal de mensagens. Dispositivos ou serviços publicam requisições para um broker; o PicoClaw assina, processa e publica as respostas de volta.
|
|
|
|
## 🚀 Início rápido
|
|
|
|
**1. Adicione o canal ao `~/.picoclaw/config.json`:**
|
|
|
|
```json
|
|
{
|
|
"channel_list": {
|
|
"mqtt": {
|
|
"enabled": true,
|
|
"type": "mqtt",
|
|
"settings": {
|
|
"broker": "tcp://localhost:1883",
|
|
"agent_id": "assistant"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**2. Inicie o gateway:**
|
|
|
|
```bash
|
|
picoclaw gateway
|
|
```
|
|
|
|
**3. Envie uma mensagem de qualquer cliente MQTT:**
|
|
|
|
```bash
|
|
mosquitto_pub -t "/picoclaw/assistant/device1/request" \
|
|
-m '{"text": "Qual é o uso de CPU?"}'
|
|
```
|
|
|
|
**4. Assine para receber a resposta:**
|
|
|
|
```bash
|
|
mosquitto_sub -t "/picoclaw/assistant/device1/response"
|
|
```
|
|
|
|
---
|
|
|
|
## 📨 Estrutura de tópicos
|
|
|
|
```
|
|
{prefix}/{agent_id}/{client_id}/request # Cliente → PicoClaw
|
|
{prefix}/{agent_id}/{client_id}/response # PicoClaw → Cliente
|
|
```
|
|
|
|
| Segmento | Descrição |
|
|
|----------|-----------|
|
|
| `prefix` | Prefixo do tópico configurado no servidor. Padrão: `/picoclaw` |
|
|
| `agent_id` | Identificador da instância do PicoClaw, definido no campo `agent_id` |
|
|
| `client_id` | Identificador de sessão definido pelo cliente — use um ID estável por dispositivo para manter o contexto da conversa |
|
|
|
|
### Payload da mensagem (JSON)
|
|
|
|
```json
|
|
{ "text": "sua mensagem aqui" }
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Configuração
|
|
|
|
### config.json
|
|
|
|
```json
|
|
{
|
|
"channel_list": {
|
|
"mqtt": {
|
|
"enabled": true,
|
|
"type": "mqtt",
|
|
"settings": {
|
|
"broker": "ssl://seu-broker:8883",
|
|
"agent_id": "assistant",
|
|
"topic_prefix": "/picoclaw",
|
|
"client_id": "",
|
|
"keep_alive": 60,
|
|
"qos": 0
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### .security.yml (credenciais)
|
|
|
|
O nome de usuário e a senha são armazenados em `~/.picoclaw/.security.yml`, não no `config.json`:
|
|
|
|
```yaml
|
|
channel_list:
|
|
mqtt:
|
|
settings:
|
|
username: seu_usuario
|
|
password: sua_senha
|
|
```
|
|
|
|
### Campos de configuração
|
|
|
|
| Campo | Local | Obrigatório | Padrão | Descrição |
|
|
|-------|-------|-------------|--------|-----------|
|
|
| `broker` | `settings` | Sim | — | URL do broker MQTT, ex. `tcp://host:1883`, `ssl://host:8883` |
|
|
| `agent_id` | `settings` | Sim | — | Identificador do agente, usado como parte do caminho do tópico |
|
|
| `topic_prefix` | `settings` | Não | `/picoclaw` | Prefixo do namespace dos tópicos |
|
|
| `username` | `.security.yml` | Não | — | Nome de usuário para autenticação no broker |
|
|
| `password` | `.security.yml` | Não | — | Senha para autenticação no broker |
|
|
| `client_id` | `settings` | Não | gerado automaticamente | ID de cliente paho enviado ao broker. Gerado automaticamente como `picoclaw-mqtt-{agent_id}-{8 hex}` se não definido; fixo durante o tempo de vida do processo e reutilizado nas reconexões |
|
|
| `keep_alive` | `settings` | Não | `60` | Intervalo de keepalive MQTT em segundos |
|
|
| `qos` | `settings` | Não | `0` | Nível de QoS para publicação e assinatura: `0`, `1` ou `2` |
|
|
|
|
### Variáveis de ambiente
|
|
|
|
| Variável | Campo |
|
|
|----------|-------|
|
|
| `PICOCLAW_CHANNELS_MQTT_BROKER` | `broker` |
|
|
| `PICOCLAW_CHANNELS_MQTT_AGENT_ID` | `agent_id` |
|
|
| `PICOCLAW_CHANNELS_MQTT_TOPIC_PREFIX` | `topic_prefix` |
|
|
| `PICOCLAW_CHANNELS_MQTT_USERNAME` | `username` |
|
|
| `PICOCLAW_CHANNELS_MQTT_PASSWORD` | `password` |
|
|
| `PICOCLAW_CHANNELS_MQTT_CLIENT_ID` | `client_id` |
|
|
| `PICOCLAW_CHANNELS_MQTT_KEEP_ALIVE` | `keep_alive` |
|
|
| `PICOCLAW_CHANNELS_MQTT_QOS` | `qos` |
|
|
|
|
---
|
|
|
|
## 🔄 Reconexão
|
|
|
|
O PicoClaw reconecta automaticamente ao broker se a conexão for perdida, com intervalo de 5 segundos. Após a reconexão, a assinatura é restabelecida automaticamente. O ID de cliente no broker permanece o mesmo nas reconexões, permitindo que o broker identifique corretamente a mesma sessão.
|
|
|
|
---
|
|
|
|
## ⚠️ Observações
|
|
|
|
- **TLS**: SSL/TLS é suportado (URL do broker com `ssl://`). A verificação de certificado é ignorada por padrão.
|
|
- **Respostas em streaming**: Respostas em streaming enviam múltiplas mensagens para o tópico de resposta; concatene-as na ordem recebida para obter a resposta completa.
|
|
- **client_id vs ID de sessão**: O `client_id` no caminho do tópico é definido pela sua aplicação cliente e identifica a sessão. É separado do ID de cliente paho usado pelo PicoClaw para se conectar ao broker.
|
|
- **Múltiplas instâncias**: Se várias instâncias do PicoClaw usarem o mesmo `agent_id` no mesmo broker, defina `client_id` distintos para evitar conflitos no nível do broker.
|