MQTT no MATLAB e no Simulink: assinar, publicar e analisar dados

O MATLAB conversa com qualquer broker MQTT usando uma única função: mqttclient, parte do Industrial Communication Toolbox. Ela conecta, assina, publica e guarda as mensagens recebidas em um timetable, que é exatamente o formato que o MATLAB quer para análise. Este tutorial percorre um fluxo completo: conectar a um broker, coletar dados de sensores, publicar comandos, analisar o resultado e o que fazer no Simulink ou quando você não tem o toolbox.

O que você precisa

• MATLAB com Industrial Communication Toolbox (o antigo OPC Toolbox, que ganhou suporte a MQTT no R2022a). Verifique com ver ou which mqttclient.
• Um broker. Os exemplos usam o endpoint de testes compartilhado broker.connectmq.com (TCP 1883, TLS 8883).
• Um segundo cliente para observar o tráfego, como o cliente MQTT online ou o mosquitto_sub.

Use um prefixo de topic único, como testmqtt/matlab/<seu-nome>/..., para que seus dados de teste não se misturem com os de outros usuários de um broker compartilhado.

Conectar ao broker

O mqttclient recebe o endereço do broker com um esquema (tcp://, ssl://, ws:// ou wss://) e as opções como argumentos nome-valor:

client = mqttclient("tcp://broker.connectmq.com", ...
    Port=1883, ...
    ClientID="matlab-" + string(randi(1e6)), ...
    KeepAliveDuration=seconds(60));

client.Connected   % true quando o CONNECT foi aceito

Para um broker com autenticação, leia as credenciais de variáveis de ambiente em vez de deixá-las fixas em um script que você talvez compartilhe:

client = mqttclient("ssl://broker.connectmq.com", ...
    Port=8883, ...
    Username=getenv("MQTT_USER"), ...
    Password=getenv("MQTT_PASS"), ...
    CARootCertificate="ca.pem");

CARootCertificate aponta para um arquivo PEM com a CA que assinou o certificado do broker. Para TLS mútuo, adicione ClientCertificate e ClientKey. Se a conexão falhar, verifique primeiro a cadeia de certificados fora do MATLAB; veja como testar uma conexão MQTT com TLS.

Assinar: callback ou buffer

Existem duas formas de receber mensagens, e escolher a certa importa mais no MATLAB do que em outras linguagens.

Modo buffer (sem callback): guarda as mensagens recebidas dentro do objeto cliente. Você as busca depois com read. É ideal para análise de dados, porque você recebe um timetable em uma única chamada:

subscribe(client, "testmqtt/matlab/sensors/+/temp", QualityOfService=1);
pause(30)                        % coletar por 30 segundos
msgs = read(client);             % timetable: Time, Topic, Data
head(msgs)

Modo callback: executa uma função para cada mensagem. Use para reações ao vivo, como atualizar um gráfico ou disparar um alarme:

subscribe(client, "testmqtt/matlab/alarms/#", Callback=@onAlarm);

function onAlarm(topic, data)
    fprintf("%s  %s -> %s\n", string(datetime("now")), topic, data);
end

O callback recebe o topic e o payload. Mantenha-o curto: ele roda na thread do MATLAB, então um cálculo pesado dentro dele atrasa todas as mensagens seguintes. Os filtros de topic seguem as regras normais do MQTT (+ casa com um nível, # com o resto); teste um filtro contra topics reais com o topic matcher antes de se perguntar por que nada chega.

Outras funções úteis: peek(client) mostra as mensagens mais recentes do buffer sem removê-las, unsubscribe(client, topic) encerra uma assinatura, flush(client) esvazia o buffer e client.Subscriptions lista o que está ativo.

Publicar a partir do MATLAB

write envia uma mensagem. Codifique dados estruturados com jsonencode para que qualquer outro cliente consiga interpretá-los:

for k = 1:60
    for id = ["s1" "s2" "s3"]
        msg = jsonencode(struct( ...
            "value", 20 + 2*randn(), ...
            "ts", posixtime(datetime("now"))));
        write(client, "testmqtt/matlab/sensors/" + id + "/temp", msg, ...
            QualityOfService=1);
    end
    pause(1)
end

Passe Retain=true para estados que assinantes tardios devem ver imediatamente, como um setpoint ou a versão de um modelo. QoS 1 garante entrega pelo menos uma vez entre o MATLAB e o broker; veja níveis de QoS do MQTT para entender os trade-offs.

Acompanhe o resultado em uma segunda janela: abra o cliente online, assine testmqtt/matlab/# e você deve ver três topics sendo atualizados a cada segundo.

Veja suas mensagens do MATLAB no navegador

Analisar os dados

É aqui que o MATLAB brilha. read retorna um timetable cuja variável Data contém os payloads como strings. Decodifique-os, monte um timetable limpo e reamostre:

msgs = read(client);

value = arrayfun(@(s) getfield(jsondecode(s), "value"), msgs.Data);
sensor = extractBetween(msgs.Topic, "sensors/", "/temp");

tt = timetable(msgs.Time, categorical(sensor), value, ...
    VariableNames=["Sensor" "Value"]);

% Média por minuto e por sensor
perMinute = groupsummary(timetable2table(tt), ...
    ["Sensor" "Time"], {"none" "minute"}, "mean", "Value");

% Suavizar e plotar
figure; hold on
for s = categories(tt.Sensor)'
    t = tt(tt.Sensor == s{1}, :);
    plot(t.Time, smoothdata(t.Value, "movmean", 10), DisplayName=s{1});
end
legend; ylabel("Temperatura (°C)"); title("Dados de sensores MQTT")

Algumas observações práticas:

• msgs.Time é o momento em que a mensagem chegou ao MATLAB, não quando o dispositivo fez a medição. Se o tempo importa, inclua um timestamp no payload (como acima) e use esse valor. A diferença de relógio entre dispositivos é uma fonte clássica de gráficos confusos.
• A decodificação falha com JSON malformado. Envolva o jsondecode em try/catch para dados reais de dispositivos, ou filtre antes com startsWith(msgs.Data, "{").
• O buffer cresce enquanto você não lê. Em execuções longas, chame read periodicamente e acrescente os dados a um arquivo com writetimetable, ou grave em disco desde o início (veja registrar MQTT em CSV para o mesmo padrão em Python).

O design do payload torna esta etapa fácil ou dolorosa. JSON curto e plano, com unidades e timestamps explícitos, é o formato mais amigável para análise; veja boas práticas de design de payload.

MQTT no Simulink

Para modelos que precisam trocar sinais com dispositivos reais, as versões recentes do Industrial Communication Toolbox oferecem os blocos MQTT Publish e MQTT Subscribe, e os pacotes de suporte de hardware (por exemplo, o do Raspberry Pi) trazem seus próprios blocos MQTT para geração de código no alvo. O conjunto exato de blocos e opções depende da sua versão, então confira a biblioteca de blocos da sua instalação.

Usos típicos:

• Hardware-in-the-loop: um modelo de planta no Simulink assina os comandos de atuadores de um controlador real e publica valores de sensores simulados.
• Dashboards de gêmeo digital: um modelo em execução publica seus estados para que um dashboard web os exiba.
• Ajuste de parâmetros: um bloco assinante recebe setpoints publicados pelo MATLAB ou por um navegador enquanto a simulação roda.

Por padrão, o Simulink roda o mais rápido possível. Ao conectá-lo ao MQTT, ative o simulation pacing (ou use um alvo de tempo real) para que o modelo não inunde o broker com milhares de mensagens por segundo de tempo simulado.

Sem o toolbox: use Python a partir do MATLAB

Se o Industrial Communication Toolbox não estiver disponível, a interface Python do MATLAB pode chamar o paho-mqtt diretamente. Instale-o no ambiente Python informado por pyenv (pip install paho-mqtt) e use as funções bloqueantes do paho:

% Publicar uma mensagem
py.paho.mqtt.publish.single("testmqtt/matlab/cmd", "start", ...
    pyargs("hostname", "broker.connectmq.com", "port", int32(1883), "qos", int32(1)));

% Esperar 5 mensagens e retorná-las
msgs = py.paho.mqtt.subscribe.simple("testmqtt/matlab/sensors/#", ...
    pyargs("hostname", "broker.connectmq.com", "msg_count", int32(5)));

for k = 1:length(msgs)
    m = msgs{k};
    fprintf("%s: %s\n", string(m.topic), string(m.payload.decode()));
end

Isso funciona bem para scripts e jobs em lote. Para fluxos contínuos, rode fora do MATLAB uma pequena bridge em Python ou Node.js que grave em um arquivo ou banco de dados e analise isso com o MATLAB; ela sobrevive a reinícios do MATLAB e mantém seu código de análise simples.

Solução de problemas

Resumo

O mqttclient transforma o MATLAB em um cliente MQTT completo: conecte com tcp:// ou ssl://, assine em modo buffer para análise ou com callback para reações ao vivo, publique JSON com write e transforme mensagens em timetables com read. Valide topics e payloads com um segundo cliente antes de escrever código de análise, inclua timestamps do dispositivo nos payloads e leve a coleta de longa duração para um arquivo ou banco de dados quando o experimento virar um pipeline. Para arquiteturas industriais em torno disso, veja MQTT em IIoT e Indústria 4.0.

Perguntas frequentes