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 get Telemetry, 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 clientId empty 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.