Skip to main content

UDMI (Universal Device Management Interface)

The UDMI data source connects Mango to cloud IoT platforms using the Universal Device Management Interface specification. UDMI provides a high-level standard for the management and operation of physical IoT systems, typically exchanging data with a cloud entity that maintains a "digital twin" or shadow device in the cloud.

This module publishes Mango data points to a cloud IoT registry (ClearBlade, Google Cloud IoT / GBOS, or a custom MQTT broker) and keeps the cloud device shadow synchronized with real-time values from your connected equipment.

Overview​

PropertyValue
Modulemango-udmi-module
ProtocolUDMI over MQTT
DirectionPublish (Mango → Cloud)
Supported providersClearBlade, GBOS (Google Cloud IoT), MQTT
Typical useSending Mango data to cloud IoT platforms for digital twins, remote monitoring, and analytics

Prerequisites​

Before configuring UDMI publishers, you need:

  • The mango-udmi-module installed on your Mango instance.
  • An IoT project set up in your cloud provider (ClearBlade, GBOS, or a self-hosted MQTT broker).
  • A device registry and at least one device registered in that project.
  • A private/public key pair for each device. Keys can be generated at UDMI Auth Key Generator.
  • For MQTT providers: the CA certificate for the broker and a client certificate.

System Settings​

Configure shared UDMI settings before creating publishers. Navigate to Administration > System Settings > UDMI.

SettingDescription
IoT providerCLEARBLADE, GBOS, or MQTT. Determines the cloud platform for all publishers using these settings.
Project IDYour cloud project identifier.
Cloud regionCloud deployment region (e.g., us-central1).
Registry IDThe IoT device registry identifier.
SiteSite name — usually the same as the Registry ID.

Save vs. Save & Apply​

  • Save — Updates settings for new publishers only. Existing publishers keep their current configuration until restarted.
  • Save & Apply — Clears all persistent connections and restarts any running UDMI publishers to apply the new configuration immediately.

Exporting the Site Model​

Use the Export button to download the UDMI site model. The site model is used as input to the Registrar tool to register your devices in the cloud.

Creating a UDMI Publisher​

Each UDMI publisher corresponds to one device in your cloud registry.

  1. Navigate to Data Sources and create a new data source, or open an existing data source that has the equipment you want to publish.
  2. In the data source, find the UDMI section and click Add Publisher.
  3. Configure the publisher as described below.
  4. Enable the publisher to begin sending data to the cloud.

Publisher Configuration​

FieldDescription
Private Key (PEM)Required. The device private key in PEM format. Used to authenticate the MQTT connection to the cloud broker.
Public Key (PEM)Required for device registration and site model export. Paired with the private key.
CA CertificateRequired for MQTT providers. The trusted root CA certificate used to verify the broker's TLS certificate.
Client CertificateRequired for MQTT providers. The client certificate (may include intermediate certificates).

MQTT Configuration Subscription​

The toggle labeled Enable/Disable MQTT configuration subscription controls whether this publisher listens for configuration updates pushed from the cloud. When enabled, the cloud can push configuration changes to the device; when disabled, the publisher only sends data.

Device Logs​

Log files for each publisher are stored in the Mango file store. Once a publisher is enabled, log files are created automatically. Enabling messageTrace causes Mango to store each config, state, and event message with its timestamp rather than only the last message per type.

Discovery​

Platform Manager provides three discovery modes to help populate the UDMI site model and map Mango data points to UDMI device points.

Discovery TypeWhat It Finds
iotUDMI devices already configured in this Mango instance
vendorMango data sources — results can be used for UDMI point mapping
bacnetDevices found via BACnet network scan (requires a BACnet local device configured in Mango)

BACnet Discovery​

To activate BACnet discovery for UDMI devices:

  1. Configure a BACnet local device in Mango (Administration > BACnet Settings).
  2. UDMI device entries are automatically updated with BACnet discovery capabilities.
  3. You may need to re-export the site model to get updated device metadata.

BACnet discovery runs once at startup, then reschedules itself every 60 minutes. After configuring local devices, wait for the next scan before the discovered devices appear in UDMI.

Test your BACnet local device configuration using the BACnet Device Browser.

Sequencer Testing​

The UDMI Sequencer is a testing tool for verifying UDMI compliance. Mango generates the required device metadata for Sequencer tests when the following conditions are met:

Test CaseRequirement
writeback_invalidThe device has at least 1 published (non-settable) point
writeback_successThe device has at least 1 settable point (see Virtual Data Source)
writeback_failureThe device has at least 1 non-settable point
single_scan, periodic_scanA BACnet local device is configured and can discover at least 1 device

Use the latest exported site model as input to the Registrar and Sequencer tools.

Troubleshooting​

SymptomLikely CauseResolution
Publisher fails to connectInvalid private key or wrong CA certificateVerify keys were generated for the correct device and cloud provider. Re-generate if needed.
No data in cloud after enablingData points not mapped to the publisherConfirm data points are assigned to the UDMI publisher.
BACnet devices not appearing in UDMI discoveryLocal device not configured or scan not yet runConfigure BACnet local device and wait up to 60 minutes for the next scan.
"Save & Apply" causes brief data gapAll publishers restart on Save & ApplyUse Save (not Save & Apply) during active monitoring; apply changes during a maintenance window.