More Protocols & Discovery

Overview

Beyond the dedicated industrial protocols, ControlBird ships a family of lighter-weight connectors aimed at IoT, web, and edge devices (HTTP, CoAP, NATS, and BLE), together with a set of discovery services that scan the network and find compatible devices automatically. Every connector follows the same controller / endpoint / mapper pattern used by the other protocols and is configured entirely through the Device Manager application; no service-level configuration files are required.

Discovery services (mDNS, SSDP, NetScan, and BLE) probe the local network and, when edge devices are connected, run concurrently against those edge adapters as well. Once a BLE peripheral is paired, its GATT characteristics can be read and written over either the local Bluetooth adapter or an edge adapter. Discovered devices can then be mapped to Store entities with HttpMapper, CoapMapper, NatsMapper, or BleMapper to create read/write points.

Connectors at a Glance

HTTP

The HTTP connector works in two roles. The client role polls remote REST APIs on an interval and maps JSON or XML responses into Store fields, and can also issue writes back to the API. The server role hosts an HTTP endpoint that exposes ControlBird data over REST and accepts inbound webhooks. The relevant entities are HttpClientController / HttpClientEndpoint, HttpServerController / HttpServerEndpoint, and the shared HttpMapper.

Authentication

The HTTP client supports a range of authentication methods on the AuthType field of HttpClientEndpoint:

Mapping requests and responses

Each HttpMapper binds an HTTP request or response to a single entity field. The Method field selects the verb (GET, POST, PUT, PATCH, DELETE), and Path sets the resource relative to the endpoint's BaseUrl (client) or BasePath (server).

Custom default headers and a per-request timeout (default 30 seconds) can be configured. For securing a server endpoint with TLS, set TlsEnabled and link a Certificate; see Certificates.

Example: poll a weather API

HttpClientEndpoint
  BaseUrl:      https://api.openweathermap.org/data/2.5
  AuthType:     ApiKey
  ApiKeyHeader: X-API-Key
  ApiKey:       <your key>
  TimeoutMs:    30000

HttpMapper
  Direction:        Read
  Method:           GET
  Path:             /weather?q=London
  ContentType:      ApplicationJson
  ResponseJsonPath: $.main.temp
  PollIntervalMs:   60000
  TargetEntity:     <weather entity>
  TargetField:      <temperature field>

CoAP

The Constrained Application Protocol is a compact, UDP-based request/response protocol designed for low-power devices. ControlBird implements both a CoapClientController (with CoapClientEndpoint) and a CoapServerController (with CoapServerEndpoint), bound to entity fields through CoapMapper. CoAP uses port 5683 by default, or 5684 for DTLS-secured CoAPS.

Messages are confirmable by default, meaning they are acknowledged and retransmitted on loss. The Observe option turns a mapper into a live subscription: the server pushes updates as the resource changes, giving real-time data without polling.

DTLS security

CoAP endpoints can be secured with DTLS by setting DtlsEnabled on the endpoint. Clients select a DtlsSecurityMode and, for pre-shared-key mode, supply a PskIdentity and PskKey. The retransmission behaviour is tuned with MaxRetransmit and TimeoutMs (default 1000 ms). Server endpoints may set RequireClientCert and link a Certificate.

Example: control a light over CoAP

CoapMapper
  Uri:           /light/brightness
  Method:        PUT
  ContentFormat: TextPlain
  Direction:     Write
  TargetEntity:  <light entity>
  TargetField:   <brightness field>

NATS

NATS is a lightweight publish/subscribe and request-reply messaging system. ControlBird connects as a client through NatsClientController and NatsClientEndpoint, and binds subjects to entity fields with NatsMapper. The default broker port is 4222. Endpoints support username/password, token authentication, a ClientName, and TLS via TlsEnabled.

Example: subscribe to sensor data

NatsMapper
  Subject:       devices.sensor.temperature
  Direction:     Read
  PayloadFormat: Json
  QueueGroup:    sensors
  TargetEntity:  <sensor entity>
  TargetField:   <value field>

Bluetooth Low Energy (BLE)

BLE support has two parts. A BleController discovers nearby Bluetooth Low Energy devices through the host's Bluetooth stack, the same way mDNS, SSDP, and NetScan discover other device types. Once a peripheral is paired, a separate BleClientController connects to it over GATT to read and write characteristic values, using a BleEndpoint for the connection and one or more BleMapper entities to bind individual characteristics to Store fields.

The default discovery adapter is hci0, configurable with the AdapterName field, and the scan duration is set with DiscoveryTimeoutMs.

BleController
  AdapterName:        hci1
  DiscoveryTimeoutMs: 15000

Pairing

A GATT characteristic cannot be read or written until its peripheral is paired. To pair a device, select a discovered Bluetooth device in the Device Manager tree and pair it from its detail pane. Depending on what the peripheral supports, ControlBird may prompt for a PIN code, a passkey, confirmation of a passkey shown on the peripheral (numeric comparison), or a plain authorize/reject decision. Peripherals that support just-works pairing need none of these; the device shows a spinner and then a Paired badge with no further input required.

Pairing runs through the Bluetooth adapter on the node handling the request; a device that is only visible through an edge adapter can be discovered but not paired yet. Bonds are kept by the host's Bluetooth service: they survive a pod restart, but not replacing the node itself, so a device has to be paired again after a node replacement. If a device is unpaired from outside ControlBird, the Paired status shown in the UI can take up to 30 seconds to catch up.

Reading and writing characteristics

Each BleMapper binds one GATT characteristic, or a descriptor on one, to a Store field.

Standard BLE profiles often pack more than one value into a single characteristic, which is why ByteOffset and ByteLength matter more here than on other protocols. A Heart Rate Measurement characteristic, for example, packs a flags byte together with the heart-rate value in the same bytes.

Example: read battery level

BleEndpoint
  Address:     AA:BB:CC:DD:EE:FF
  AddressType: Public

BleMapper
  SourcePath:   180f/2a19
  Direction:    Read
  ReadMode:     Subscribe
  Encoding:     Uint8
  TargetEntity: <battery entity>
  TargetField:  <level field>

Network Discovery

Four discovery controllers scan the network for compatible devices: mDNS, SSDP, TCP port scanning (NetScan), and Bluetooth Low Energy. Each runs in dual mode (a local scan plus a concurrent edge-adapter scan) and can be launched from the Device Manager's Discovery tree group.

mDNS / Zeroconf

MdnsController discovers advertised services on the local link via multicast DNS. The default timeout is 5000 ms. By default it scans for the following service types, configurable through the ServiceTypes field: _http._tcp, _googlecast._tcp, _esphomelib._tcp, _hap._tcp, _sonos._tcp, _airplay._tcp, _ipp._tcp, and _spotify-connect._tcp. For example, set ServiceTypes to _hap._tcp to find Apple HomeKit Accessory Protocol devices.

SSDP / UPnP

SsdpController sends an M-SEARCH multicast to 239.255.255.250:1900 to discover UPnP devices, with a default timeout of 8000 ms. The SearchTargets field sets the search targets, and when FetchDescriptions is enabled the controller fetches each device's UPnP description document over HTTP (with a fixed 2000 ms timeout per device) and parses the returned XML.

NetScan

NetScanController finds IP devices by probing TCP ports across one or more subnets. The default timeout is 30000 ms; the default subnets are 192.168.1.0/24 and the default ports are 80, 443, 502, 1883, 4840, 8080, 47808. Subnets accept CIDR notation, and the scanner probes ports in parallel for fast results.

Open ports are matched against a built-in port-to-protocol map to label each discovered device:

Example: scan an industrial network

NetScanController
  Subnets: 10.0.0.0/24,10.1.0.0/24
  Ports:   502,4840,47808

UDP-TCP Bridge

For protocol tunneling, ControlBird includes a UDP-TCP bridge that relays traffic between a TCP side and a UDP side. The bridge listens on port 19000 by default and supports many concurrent connections.

Configuration Workflow

1. Open the Device Manager application in the ControlBird UI.
2. Click Add Integration to discover devices, or Create Custom to configure one manually.
3. Choose a protocol (HTTP, CoAP, or NATS) and create the matching controller and endpoint.
4. Set the connection parameters: base URL or host/port, authentication, and TLS or DTLS as required.
5. In the Device Manager tree, expand the Discovery group and run a scan to locate advertised and reachable devices.
6. Tune discovery parameters: ServiceTypes (mDNS), SearchTargets (SSDP), Subnets and Ports (NetScan), AdapterName (BLE).
7. Map discovered devices to entities with HttpMapper, CoapMapper, NatsMapper, or BleMapper to create read/write points.
8. Review active controllers and endpoints in the Device Manager tree under each protocol's section.
9. Export configured devices as CSV/JSON, or import device points to bulk-provision multiple devices.

For a hands-on introduction to binding a device to Store entities, see walkthrough step 7: Connect a Device.

Limitations

• The HTTP client does not support request pipelining or HTTP/2 multiplexing.
• OAuth 2.0 PKCE is always enabled and cannot be disabled per endpoint.
• NATS JetStream mode is not yet implemented; only Core mode is functional.
• CoAP mappers do not support custom block-transfer options for large payloads.
• The SSDP description-fetch timeout is fixed at 2000 ms per device and cannot be customized.
• NetScan only detects open TCP ports; it does not perform deep service enumeration.
• BLE pairing runs through the Bluetooth adapter on the node handling the request; a device visible only through an edge adapter can be discovered but not paired yet.
• ControlBird always initiates BLE pairing; a peripheral cannot initiate pairing on its own.
• BLE bonds are stored by the host's Bluetooth service and survive a pod restart, but not a node replacement.
• If a BLE device is unpaired outside ControlBird, the Paired status shown in the UI can take up to 30 seconds to catch up.
• All discovery timeouts are synchronous and block the controller; a running scan cannot be interrupted.
• Discovery results from mDNS, SSDP, and NetScan are not persisted; repeated scans may yield different results.
• The UDP bridge requires manual handshake negotiation and does not reconnect automatically on failure.