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. Discovered devices can then be mapped to Store entities with HttpMapper, CoapMapper, or NatsMapper 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>

BLE Discovery

The BleController discovers Bluetooth Low Energy devices through the host's Bluetooth stack on Linux. The default adapter is hci0, configurable with the AdapterName field, and the scan duration is set with DiscoveryTimeoutMs. When edge devices are connected, BLE scans run on the local adapter and the edge adapters concurrently.

BleController
  AdapterName:        hci1
  DiscoveryTimeoutMs: 15000

Network Discovery

Three discovery controllers scan the network for compatible devices. Each runs in dual mode (a local scan plus a concurrent edge-adapter scan) and is launched from the Device Manager's Scan Network action.

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. Click Scan Network to run discovery: mDNS, SSDP, NetScan, and BLE 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, or NatsMapper to create read/write points.
8. Review active controllers and endpoints in the My Integrations tab.
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 discovery is limited to advertised services and cannot perform large-scale GATT characteristic discovery.
• 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.