Topics#

Introduction#

This section of the documentation will outline how to configure mqttwarn topics. You will learn how to subscribe to MQTT topics, and map them to the services you have defined.

mqttwarn’s topic configuration subsystem relates 1:1 to MQTT’s topics. You will configure topic subscriptions in the same way you are used to, using the same wildcard scheme you are already accustomed to, for example when using mosquitto_pub.

The [__topic__] sections#

All sections not called [defaults] or [config:xxx] are treated as MQTT topics to subscribe to. mqttwarn handles each message received on this subscription by handing it off to one or more service targets.

Section names must be unique and must specify the name of the topic to be processed. If the section block does not have a topic option, then the section name will be used.

When a message is received at a topic with more than one matching sections, it will be directed to the targets in all matching sections. For consistency, it’s a good practice to explicitly provide topic options to all such sections.

A section can have additional mandatory (M) or optional (O) options:

Option

M/O

Description

targets

M

service targets for this SUB

topic

O

topic to subscribe to (overrides section name)

filter

O

function name to suppress this msg

datamap

O

function name parse topic name to dict

alldata

O

function to merge topic, and payload with more

format

O

function or string format for output

priority

O

used by certain targets (see below). May be func()

title

O

used by certain targets (see below). May be func()

image

O

used by certain targets (see below). May be func()

template

O

use Jinja2 template instead of format

qos

O

MQTT QoS for subscription (dflt: 0)

Basic message routing#

Consider the following example configuration.

[icinga/+/+]
targets = log:info, file:f01, mysql:nagios

[my/special]
targets = mysql:m1, log:info

[my-other-special]
topic = another/topic
targets = log:debug

  • MQTT messages received at icinga/+/+ will be directed to the three specified targets.

  • Messages received at my/special will be stored in a mysql target and will be logged at level “INFO”.

  • Messages received at another/topic (not at my-other-special) will be logged at level “DEBUG”.

Advanced message routing#

Dictionary targets#

Targets can also be defined as a dictionary, containing items of {topic: targets}. In that case, message matching the section can be dispatched in more flexible ways to selected targets. Consider the following example:

[#]
targets = {
  '/#': 'file:0',
  '/test/#': 'file:1',
  '/test/out/#': 'file:2',
  '/test/out/+': 'file:3',
  '/test/out/+/+': 'file:4',
  '/test/out/+/state': 'file:5',
  '/test/out/FL_power_consumption/state': [ 'file:6', 'file:7' ],
  '/test/out/BR_ambient_power_sensor/state': 'file:8',
  }

With such a message dispatching configuration, the message is dispatched to the targets matching the most specific topic.

  • If the message is received at /test/out/FL_power_consumption/state, it will be directed to file:6 and file:7 targets only.

  • A message received at /test/out/AR_lamp/state will be directed to file:5.

  • A message received at /test/out/AR_lamp/command will go to file:4.

The dispatcher mechanism is always trying to find the most specific match. It allows to define the wide topic with default targets while some more specific topics can be handled differently. It gives additional flexibility in message routing.

Attention

The closing brace } of the targets dictionary MUST be indented. This is an artifact of Python’s ConfigParser.

Templated targets#

By defining topic targets as templates, and interpolating transformation data, we can make mqttwarn dispatch messages dynamically, based on the values of the transformation data dictionary.

By bundling multiple target rules into a single templated one, this may save a few explicit rules to be configured within your topic section definitions.

Example 1#

To get an idea about how this works, let’s define the placeholder variable loglevel inside the targets option of a topic section.

[topic-targets-dynamic]
topic   = test/topic-targets-dynamic
format  = Something {loglevel} happened! {message}
targets = log:{loglevel}

When sending this value through a JSON encoded message or by computing it through the alldata transformation machinery, it will get interpolated into the designated topic target. Example:

mosquitto_pub \
  -t test/topic-targets-dynamic \
  -m '{"loglevel": "crit", "message": "Nur Döner macht schöner!"}'

This will issue the following message into the log file:

2016-02-14 18:09:34,822 CRITICAL [log] Something crit happened! Nur Döner macht schöner!

While this little example might feel artificial, there are more sensible use cases like determining the recipient address of smtp or xmpp receivers by interpolating information from topic names or message payloads. Please have a look at how to incorporate topic names into topic targets for a more meaningful example in this regard.

Example 2#

The Frigate » Forward events and snapshots to ntfy tutorial used a configuration snippet like this.

[frigate/cam1/goat/snapshot]
targets = store-image:cam1-goat
[frigate/cam2/squirrel/snapshot]
targets = store-image:cam2-squirrel

Using Templated targets, this can be condensed like this, not needing to repeat each and every slot to be addressed. Of course, it needs a corresponding Decoding function to propagate the camera and label values into the transformation data.

[frigate/+/+/snapshot]
targets = store-image:{camera}-{label}