Device Manager

Overview

The Device Manager is the application you use to discover, create, and manage the protocol integrations that bring real-time device data into ControlBird. It sits on top of a hierarchical schema of Protocol Controllers, Endpoints, and Mappers: the entities that bind a device's raw data (Modbus registers, MQTT topics, OPC UA nodes) to fields on entities in your Store. Supported protocols include Modbus, MQTT, OPC UA, BACnet, DNP3, EtherNet/IP, HTTP, CoAP, NATS, and SMTP, each backed by a service extension in the catalog.

The Device Manager offers two paths to the same result. The guided integration path uses prebuilt templates and a wizard to auto-generate the controller, endpoint, and mapper entities for you. The custom device path lets you create those entities by hand for protocols or devices that have no prebuilt template. Use a guided integration whenever a template exists (Ecobee, Tasmota, an MQTT broker, a Modbus TCP service, and so on); reach for a custom device when you need full manual control over points and addressing.

Key Concepts

Two paradigms underpin the Device Manager. A protocol defines the wire mechanics through three entity layers; an integration is a prebuilt configuration that auto-generates those protocol entities for you.

Each protocol adds its own configuration options on top of these concepts. A Modbus integration, for example, exposes protocol-specific mapper settings such as register type, address, and byte order. See the Modbus guide for the full Modbus-specific reference.

The Workspace

The Device Manager UI presents two main tabs and a toolbar of actions.

• Devices: a list/grid view of all devices with search, filter, and sort. Supports virtual scrolling, bulk select, and per-point operations.
• My Integrations: browse the integrations you have configured and rediscover devices from each one.

The Integration Wizard

The Integration Wizard walks you through a five-step flow to add a prebuilt integration. Each step renders dynamically from the integration's configuration form, then runs its discovery and provision steps.

1. Select Integration: choose an integration from the catalog.
2. Connection: fill in the connection configuration form.
3. Discovery: discover available devices and select which ones to provision.
4. Configure: map device attributes to your entity tree.
5. Provision: create the controller, endpoint, and mapper entities for the selected devices.

Common Patterns

• Guided first, custom as fallback. When a template exists for your device, use Add Integration; it generates the controller, endpoint, and mapper entities for you. Use Create Custom only when no template applies.
• Subscribe vs. Poll. Set a mapper's ReadMode to Subscribe for event-driven protocols that emit change notifications, and Poll with a suitable PollIntervalMs for protocols that require periodic reads.
• Rediscover to resync. When an integration's source changes (a device is added or renamed), open My Integrations and use Rediscover rather than editing generated points by hand.
• Bulk import/export for migration. Use the Import and Export actions (CSV/JSON) to move device definitions between environments or to back them up.
• Network scan to find devices. Use Scan Network (mDNS, SSDP, network scanning) to locate devices on the local network, then provision the results into controllers and mappers.

Troubleshooting & Limitations

• Integration devices are read-only. Devices marked as integration devices cannot have points added, edited, or deleted directly. To change them, re-run discovery or rediscovery to sync with the integration source.
• Choose one editing path per device. Custom devices allow manual point creation; integrations generate points automatically via provision programs. Mixing the two on one device conflicts, so pick one path.
• Connection mode must match the protocol. A controller's connection mode defaults to a single active connection with automatic failover. Changing it affects failover behavior; some protocols (e.g. MQTT) need to allow multiple concurrent connections.
• Don't mix read modes on one endpoint. Subscribe expects the device to emit change notifications and Poll falls back to periodic reads; mixing modes on the same endpoint can lead to duplicate data.
• Bulk operations respect the current view. Bulk delete and export apply to the currently visible result set (after search/filter), not all devices, so apply filters carefully.
• Custom devices lack auto-populated metadata. Manufacturer, model, device type, and image are inferred from integration discovery; manually created devices use defaults.
• Add guardrails for writes. Use Alarm Behaviors or Rule Chains to enforce business-logic constraints on writes to device points.
• Network scan is advisory only. Scan results (mDNS, SSDP, and network discovery) must be manually provisioned into controllers and mappers before they take effect.