Skip to main content

bedaya_mqtt 0.1.2 copy "bedaya_mqtt: ^0.1.2" to clipboard
bedaya_mqtt: ^0.1.2 copied to clipboard

Reliable MQTT for Flutter & Dart IoT apps. Auto reconnect, offline queue, typed topics, device and controller roles.

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.

0
likes
160
points
546
downloads

Documentation

API reference

Publisher

verified publisherbedaya.dev

Weekly Downloads

Reliable MQTT for Flutter & Dart IoT apps. Auto reconnect, offline queue, typed topics, device and controller roles.

Repository (GitHub)
View/report issues

Topics

#mqtt #iot #esp32 #websocket #messaging

License

BSD-3-Clause (license)

Dependencies

mqtt_client, typed_data

More

Packages that depend on bedaya_mqtt