bedaya_mqtt
Typed, reliable MQTT for Dart: reconnect, offline queue, typed topics. Built by Bedaya.
bedaya_mqtt sits on top of mqtt_client
and adds the parts every IoT app ends up writing by hand:
- Automatic reconnect with exponential backoff and jitter, and every subscription restored afterwards.
- Offline queue: publish while offline, and messages are sent once the connection is back.
- Typed topics:
Topic<T>with{param}patterns. You getTelemetry, not bytes. - Two roles: a controller that watches devices and sends commands, and a device that publishes data and answers them, with online/offline status and a Last Will.
- Clean streams: a bad payload from someone else on the broker is skipped and reported, and your stream keeps going.
- Everywhere Dart runs: Flutter (mobile and desktop), CLI scripts, servers and the web. Pure Dart, no Flutter dependency.
- TLS, including private CAs and client certificates.
- Test helpers: an in-memory broker, so your tests need no network.
Install
dart pub add bedaya_mqtt
Quick start
These snippets use broker.hivemq.com, a free public broker that everyone
shares. Pick your own topicPrefix (your name, or anything unique), and use
the same one in the controller and the device. Otherwise you may see other
people's devices, and they may switch your relay.
Controller: watch a device and send it a command
import 'package:bedaya_mqtt/bedaya_mqtt.dart';
final client = BedayaClient(
ClientConfig(host: 'broker.hivemq.com', topicPrefix: 'bedaya-yourname'),
);
await client.connect();
final device = client.device('a1');
device.status.listen((s) => print(s.online ? 'online' : 'offline'));
device.on(BedayaTopics.telemetry).listen((t) => print('temp: ${t['temp']}'));
final ack = await device.send(Command.relay(on: true));
print(ack.ok ? 'relay is on' : 'failed: ${ack.error}');
Device: publish data and answer commands
final client = BedayaClient(
ClientConfig(host: 'broker.hivemq.com', topicPrefix: 'bedaya-yourname'),
);
// Call asDevice before connect: it sets the Last Will, so the broker
// reports the device offline if it drops off.
final me = client.asDevice('a1');
await client.connect();
me.commands.listen((command) {
if (command.name == 'relay') {
final on = command.params['on'] as bool;
// ... switch the relay ...
me.ack(command);
} else {
me.ack(command, error: 'unknown command');
}
});
await me.publish(BedayaTopics.telemetry, Telemetry({'temp': 24.5}));
The client publishes online when it connects and offline when it
disconnects. If the connection dies, the broker publishes offline for it
(the Last Will).
Runnable versions are in example/: example.dart runs both
roles in one program, and simulated_device.dart + controller.dart run in
two terminals.
Topics
Topics are written without a prefix. The client adds
ClientConfig.topicPrefix (default bedaya) in front:
| Topic | On the wire | Payload |
|---|---|---|
BedayaTopics.telemetry |
bedaya/{deviceId}/telemetry |
Telemetry: any readings, like {"temp": 24.5} |
BedayaTopics.status |
bedaya/{deviceId}/status |
DeviceStatus: {"online": true}, retained |
BedayaTopics.command |
bedaya/{deviceId}/command |
Command: {"id", "name", "params"} |
BedayaTopics.commandAck |
bedaya/{deviceId}/command/ack |
CommandAck: {"id", "ok", "error"?} |
The full contract for firmware is in
contract/contract.yaml.
Your own typed topics
class Reading {
Reading(this.lux);
factory Reading.fromJson(Map<String, dynamic> j) => Reading(j['lux'] as num);
final num lux;
Map<String, dynamic> toJson() => {'lux': lux};
}
final light = Topic.json(
'{room}/light',
fromJson: Reading.fromJson,
toJson: (r) => r.toJson(),
qos: Qos.atMostOnce,
);
client.subscribe(light).listen((m) {
print('${m.params['room']}: ${m.value.lux} lux'); // m.value is a Reading
});
await client.publish(light, Reading(300), params: {'room': 'kitchen'});
For payloads that are not JSON, implement MessageCodec<T> and use
Topic(pattern, codec: ...).
Connection state
client.connectionStates.listen((state) {
switch (state) {
case Connected():
print('online');
case Reconnecting(:final attempt, :final nextDelay):
print('retry #$attempt in $nextDelay');
case Failed(:final error):
print('gave up: $error');
case Disconnected() || Connecting():
break;
}
});
Reconnect
On by default: about 1s, 2s, 4s, 8s, 16s, then every 30s, ±20%, forever.
ClientConfig(
host: 'broker.example.com',
reconnect: ReconnectPolicy(
initialDelay: Duration(seconds: 2),
maxDelay: Duration(minutes: 1),
maxAttempts: 10, // then Failed; null = forever
),
// Also retry the very first connect (for scripts that start before the
// network is up). Off by default, so a wrong host fails fast.
retryFirstConnect: true,
)
Use ReconnectPolicy.never() to turn it off.
Offline queue
While not connected, publish puts the message in a queue and returns.
After the next connect, the client resubscribes, then sends the queue in
order.
ClientConfig(
host: 'broker.example.com',
maxQueueSize: 500, // drop the oldest when full; 0 = no queue
queueTtl: Duration(minutes: 10), // drop messages older than this
)
A dropped message is reported on client.errors as a
MessageDroppedException. The default queue lives in memory. To keep
messages across app restarts, implement MessageQueue and pass it as
BedayaClient(config, queue: myQueue).
TLS
ClientConfig(
host: 'broker.example.com',
useTls: true, // port 8883 by default
// Only for a self-signed or private broker certificate:
caCertificate: await File('ca.crt').readAsString(),
// Only if the broker checks client certificates (mutual TLS):
clientCertificate: await File('client.crt').readAsString(),
clientKey: await File('client.key').readAsString(),
)
Certificates are PEM text, so they can also come from Flutter assets.
Web
In the browser the client always uses MQTT over WebSocket. Point it at the broker's WebSocket port:
ClientConfig(
host: 'broker.hivemq.com',
port: 8884, // HiveMQ's secure WebSocket port
useTls: true,
webSocketPath: '/mqtt', // the default
)
The browser checks the certificate itself, so custom certificates are not
supported on the web. On native platforms, set useWebSocket: true to use
WebSocket instead of TCP.
All devices at once
client.devices.changes.listen((all) {
for (final d in all.values) {
print('${d.id}: ${d.online ? 'online' : 'offline'}, last seen ${d.lastSeen}');
}
});
Tracing and debugging
Pass a logger to see every step the client takes. print works:
BedayaClient(ClientConfig(host: 'broker.hivemq.com', logger: print));
12:00:01.204 [info] connecting to broker.hivemq.com
12:00:01.391 [info] connected
12:00:01.392 [debug] subscribe bedaya/+/telemetry (atMostOnce)
12:00:03.410 [debug] received bedaya/a1/telemetry {"temp":24.5}
12:00:09.001 [warning] connection lost
12:00:09.002 [info] reconnect #1 in 0:00:01.000000
Each BedayaLogRecord has a level (debug, info, warning, error),
a message, the error behind it, and a time, so you can filter or send
records to your own logging. Off by default.
To understand the code itself, doc/ARCHITECTURE.md follows each operation (connect, publish, receive, reconnect, commands) through the files, and lists where to look for common problems.
Errors
| Where | What |
|---|---|
connect() |
ConnectionException: broker unreachable, or refused (for example notAuthorized) |
device.send() |
CommandTimeoutException when no ack arrives in time (10s by default) |
client.errors |
DecodeException for payloads that don't decode, MessageDroppedException when the queue is full |
Every exception extends BedayaException.
Testing your code
package:bedaya_mqtt/testing.dart has an in-memory broker that supports
wildcards, retained messages and the Last Will:
import 'package:bedaya_mqtt/bedaya_mqtt.dart';
import 'package:bedaya_mqtt/testing.dart';
final broker = MemoryBroker();
final device = BedayaClient(
ClientConfig(host: 'memory'),
transport: MemoryTransport(broker),
);
final controller = BedayaClient(
ClientConfig(host: 'memory'),
transport: MemoryTransport(broker),
);
Use transport.drop() to simulate a lost connection, and
broker.stop() / broker.start() to simulate the broker going down.
Good to know
- Client ids must be unique. Two connections with the same id keep kicking
each other off the broker. Leave
clientIdempty for a random one. - Sessions are clean: while a controller is offline, it misses messages that devices send. The offline queue covers the sender's offline time.
- A second stream on a topic that is already subscribed does not get the retained message again (brokers send it only on subscribe).
About Bedaya
Bedaya is building a Flutter app for controlling ESP devices over MQTT. This package is the free, open source part, and it works with any MQTT broker and any devices that follow the contract.
License
BSD 3-Clause. See LICENSE.
Libraries
- bedaya_mqtt
- Typed, reliable MQTT for Dart: reconnect, offline queue, typed topics.
- testing
- Test helpers: an in-memory MQTT broker, so tests run fast and without a network.