Documentation › Settings: Annotations

Settings: Annotations

Topic annotations let you attach human-readable labels and descriptions to your MQTT topics. They give BunkerAI the context it needs to understand your data and respond to natural-language questions accurately.

What Topic Annotations Are

An annotation is metadata attached to a topic pattern. Each annotation contains:

  • Topic pattern - the MQTT topic or wildcard pattern the annotation applies to
  • Label - a short human-readable name (e.g., "Kitchen Temperature Sensor")
  • Description - a longer explanation of what the topic carries, what values it uses, and any relevant context

Annotations are stored in your BunkerM instance and are automatically included in every AI request.

Why Annotations Matter

Without annotations, BunkerAI sees raw topic strings like h/lr/t. With annotations, it knows that h/lr/t is the living room temperature sensor reading in Celsius. This makes the AI dramatically more useful:

  • More accurate responses - the AI answers in terms of what things actually are, not raw topic names.
  • Better natural-language control - say "show me all temperature sensors" and the AI knows which topics to check.
  • Smarter anomaly analysis - alerts say "the kitchen temperature sensor published an unusually high value" instead of showing a raw topic string.
  • Faster interactions - you do not need to explain your topic structure in every conversation.

Creating an Annotation

  1. Navigate to Settings > Annotations.
  2. Click Add Annotation.
  3. Enter the Topic Pattern.
  4. Enter a Label - a short descriptive name.
  5. Enter a Description - what this topic is, what values it carries, what units are used.
  6. Click Save.

Wildcard Support

Annotations support standard MQTT wildcards:

  • sensor/+/temperature - covers all temperature topics one level under sensor/
  • sensor/# - covers everything under the sensor/ tree

More specific patterns take priority in AI context. Use specific patterns for specific annotations and broader wildcards for general category descriptions.

Example Annotations

Specific topic:

  • Pattern: home/living-room/temperature
  • Label: Living Room Temperature
  • Description: Temperature reading in Celsius from the wall-mounted Zigbee sensor. Publishes every 5 minutes. Normal range 18-24 C.

Actuator topics:

  • Pattern: actuator/lights/+/command
  • Label: Light Control Command
  • Description: Command topic for smart light controllers. Payload is JSON with "state" (on/off) and optional "brightness" (0-100). Third level is the room name.

Device status:

  • Pattern: device/+/status
  • Label: Device Status
  • Description: Heartbeat topic for IoT devices. Payload is "online" or "offline", published on connect/disconnect via MQTT will messages.

Managing Annotations

  • Edit - click any annotation to update its label, description, or pattern.
  • Delete - remove an annotation you no longer need. This only removes the AI context hint; the underlying MQTT topics are unaffected.

Annotations are stored persistently with your BunkerM data.

← Settings: Integrations Settings: Subscriptions →