Device Connectivity

EmberCORE reads industrial equipment directly, in the protocols that equipment already speaks. Each device you register can have one collector per protocol, and each collector polls the tags you configure and records every value with its quality.

How collectors work

Read only, always. Every collector reads and nothing else. There are no writes, no RUN or STOP commands, no discovery broadcasts, and no scanning. A collector reads the tags you configured and leaves the rest of the network alone.

How they reach a device. If the device has a Flux service, the collector dials it over Flux, so the device never needs an exposed port. Otherwise the collector dials the device's address directly, under the outbound guard:

• Loopback, link-local (including cloud metadata addresses), multicast, and the cluster's own internal ranges are always refused.
• Private addresses are allowed only inside your organization's recorded site subnets. If a device is refused, ask Fireball to record that site's subnet for your organization.
• Public addresses are allowed.

The guard follows whoever configured the collector, so a collector can never be pointed somewhere its author could not reach.

Polling. A collector polls every five seconds unless you set another interval. A saved change takes effect within 30 seconds and restarts that collector. A device that is down is retried with backoff, from five seconds up to five minutes, and the collector never gives up on it.

Quality. Every reading is good, uncertain, or bad. A bad reading is never charted as a value: it is unknown, not zero. Recent values are kept for the device's sparklines, and readings are written to your organization's time-series bucket when EmberCORE's time-series store is enabled.

Supported protocols

Protocol	Key	Default port	Reads
OPC UA	opcua	4840	Node values, with signed and encrypted sessions
Modbus TCP and RTU over TCP	modbus	502	Coils, discrete inputs, holding and input registers
S7comm (Siemens)	s7comm	102	DB, M, I, and Q areas
EtherNet/IP (Rockwell Logix)	ethernet-ip	44818	Symbolic controller tags
MTConnect	mtconnect	5000	Samples, events, and conditions
FINS (Omron)	fins	9600	DM, CIO, W, H, and A memory areas
MELSEC / SLMP (Mitsubishi)	melsec	5007	X, Y, M, L, B, D, W, R, and ZR devices
BACnet/IP	bacnet	47808/udp	Input, output, and value objects
DNP3	dnp3	20000	Binary, analog, and counter points
3D printers	printer3d	80 or 443, Moonraker 7125	Printer state, temperatures, and job progress
MQTT	mqtt		Topics from AnvilMQ

Five more protocols ride one of these through a gateway or controller; see Gateway protocols.

OPC UA

• Security. Security policy None, Basic256Sha256, Aes128_Sha256_RsaOaep, or Aes256_Sha256_RsaPss, with mode Sign or SignAndEncrypt (the default when a policy is set). Basic256 and Basic128Rsa15 are refused, because the OPC Foundation deprecated them.
• A client certificate per organization. Signing needs a certificate the server trusts. EmberCORE creates one for your organization the first time it is needed and keeps it, so a server only has to trust it once. Each organization has its own, so a certificate one organization's server trusts cannot open another's. To trust it ahead of time, fetch it from GET /api/industrial/opcua/client-cert?tenant=<your-tenant>, which returns the certificate, its thumbprint, and its ApplicationURI.
• Server pinning. Set serverThumbprint to the server certificate's SHA-1 thumbprint, and a mismatch is refused before anything is sent. Without a pin, the server's thumbprint is logged at connect so you can pin it.
• Login. Anonymous, or username and password.
• Polling, not subscriptions. Each poll reads the configured nodes in one request. There is no browsing: list the node IDs you want, each with an explicit i=, s=, g=, or b= identifier.

Modbus

• TCP, or RTU framing over TCP for serial devices behind a TCP gateway.
• Function codes 01 to 04 only: coils, discrete inputs, holding registers, and input registers.
• Types bool, signed and unsigned 16, 32, and 64-bit integers, and 32 and 64-bit floats, with byte orders AB, BA, ABCD, CDAB, BADC, and DCBA. Each register can carry a scale, an offset, and a unit.
• Reads are batched, and if a device rejects a batched read, the collector falls back to strictly contiguous reads.

Modbus has no data types on the wire, so register maps are where mistakes hide. Check a few known values against the device before trusting a map.

S7comm

• Classic S7comm, reading the DB, M, I, and Q areas with types bool, byte, int, dint, word, dword, real, lreal, and string.
• S7-1200 and S7-1500 controllers need PUT/GET access enabled and non-optimized data blocks.

EtherNet/IP

• Reads Logix controller tags by name, batched into multiple-service requests, with types from bool through lreal and string.
• Set the route path to the controller (for example 1,0). There is no tag browsing; list the tags you want.

MTConnect

• Reads the agent's probe at connect and its current values on every poll, for MTConnect 1.x and 2.x agents. Samples, events, and conditions all become tags.
• Conditions read as numbers: Unavailable -1, Normal 0, Warning 1, and Fault 2.

FINS

• FINS over TCP, using the memory area read command only.
• Reads the DM, CIO, W, H, and A areas. The EM area is not supported.

MELSEC / SLMP

• The binary 3E frame and the batch read command only.
• Bit devices X, Y, M, L, and B, and word devices D, W, R, and ZR. SLMP has no fixed port, so 5007 is EmberCORE's default; set the port your PLC uses.

BACnet/IP

• Reads one device by its instance number, unicast. There is no Who-Is and no discovery.
• Reads analog, binary, and multi-state input, output, and value objects, and properties such as present value, name, description, out of service, reliability, and event state. It uses ReadPropertyMultiple and falls back to ReadProperty on devices that lack it.
• Over Flux, the device's Flux service must carry UDP.

DNP3

• A read-only master: every poll reads Class 0, plus whichever event classes 1 to 3 you list.
• Reads binary inputs and outputs, counters, and analog inputs and outputs.
• It never enables unsolicited reporting, and never writes, which means it does not clear an outstation's restart flag or answer its time request.

3D printers

Printer API	What is read	Status
OctoPrint	Printer state, tool and bed temperatures, and job progress. Needs an API key.	Verified against a live OctoPrint 1.11.8
Moonraker (Klipper)	The first extruder, the bed, print state, and progress. Connects only once Klipper reports ready. The API key is needed only when Moonraker authentication is on.	Built against Moonraker's documented API; not yet verified against a real printer
Duet (RepRapFirmware 3)	State, heaters, tools, and job. Standalone boards only; Duets run by a single-board computer are not supported.	Built against Duet's documented API; not yet verified against a real printer

No collector sends G-code, starts or stops a job, or changes a temperature.

MQTT and Sparkplug B

The MQTT collector reads the topics you list (by default <tenant>/<deviceId>/#) from the current values held by AnvilMQ, the platform broker. It does not connect to other brokers. Sparkplug B payloads are passed through as raw data; the collector does not decode them into individual metrics yet.

Gateway protocols

These protocols are not spoken natively. Each one reads through a real protocol that its controller or a gateway exposes, and the values are stored under the gateway protocol's name, so a HART transmitter's readings are HART's, not Modbus's.

Protocol	Rides	How
PROFINET	S7comm or OPC UA	Through the S7 controller or that PLC's OPC UA server
EtherCAT	ADS or OPC UA	Through the Beckhoff TwinCAT controller running the bus
HART	Modbus	Through a HART-to-Modbus gateway
CANopen	Modbus or OPC UA	Through a Modbus or OPC UA gateway
FANUC	MTConnect	Through the controller's MTConnect adapter

For EtherCAT over ADS, the TwinCAT controller needs an ADS route for EmberCORE, and values read while the PLC is not in RUN are marked uncertain.

Configuring a collector

Collectors are configured through the API today; there is no EmberCORE screen for them yet. You need the Admin role in the device's organization.

1. Register the device in EmberCORE, so it belongs to your organization.

2. Save a collector for it with PUT /api/industrial/config. The protocolConfig field is the protocol's own settings as a JSON object, serialized into a string.

   {
     "deviceId": "press-line-4",
     "protocol": "modbus",
     "enabled": true,
     "address": "10.20.4.15:502",
     "interval": 5,
     "protocolConfig": "{\"unitId\":1,\"mode\":\"tcp\",\"registers\":[{\"name\":\"OilTemp\",\"addr\":100,\"type\":\"holding\",\"dataType\":\"float32\",\"byteOrder\":\"ABCD\",\"unit\":\"C\"}]}"
   }

   A configuration the collector cannot use is refused with the reason, rather than failing quietly later.

3. Check it with GET /api/industrial/summary?id=<deviceId>, which lists each protocol with whether it is connected, its last poll, its last error, and its tag count.

4. Read values with GET /api/industrial/metrics?id=<deviceId>&protocol=<key>.

To stop a collector, save it again with "enabled": false.

The full set of routes is in the API Reference.

Practical advice

Give industrial devices static addresses or DHCP reservations. A device whose address moves looks exactly like a device that failed.

Turn on security wherever the protocol supports it: OPC UA security policies, and SNMPv3 for network equipment.

Pick polling intervals deliberately. Faster is not better; every poll costs the device something, and older equipment can be knocked over by an aggressive schedule.

Name tags consistently from the start. Renaming a tag after a year of history is not a pleasant operation.

Network equipment such as switches, firewalls, and UPS units is monitored over SNMP instead; see SNMP Configuration.

Next steps

• Device Monitor: the registry and health view
• SNMP Configuration: network equipment
• Alerts & Notifications: alerting on device state