Niagara: technical setup for your supplier

This page is for the person who configures the Niagara station: what we issue, how to install our certificate, how to connect, what to publish, and the point list we would like back. Work through it top to bottom.

Niagara: connect your building to us

Have you got everything?

• The connection sheet for this building: broker address and port, username, password, and the site id.
• Our CA certificate as the file mqtt-ca.crt.
• This page.

If the sheet or the certificate file is missing, ask the building owner. Do not proceed with the certificate the broker presents when you connect — the next section explains why.

Install the CA certificate

Megleren vår presenterer et serversertifikat som er signert av vår egen sertifikatutsteder (CA). Stasjonen må stole på CA-en, ikke på serversertifikatet. Slik installeres mqtt-ca.crt i Niagara — menynavnene er de engelske betegnelsene i Niagara-grensesnittet:

1. Åpne Platform → Certificate Management i Niagara.
2. Velg User Trust Store — ikke Key Store.
3. Velg Import og pek på filen mqtt-ca.crt som dere fikk fra oss.
4. Kontroller HVA som står oppført, ikke bare at noe står der: oppføringen skal være sertifikatutstederen vår — «subject» og «issuer» er samme navn, og ingen av dem er megleradressen fra tilkoblingsarket. Et sertifikat som er utstedt til megleradressen, er serversertifikatet og ikke CA-en: slett den oppføringen og importer mqtt-ca.crt i stedet.
5. Sett opp MQTT-klienten med TLS mot port 8883. Klienten verifiserer megleren mot CA-en som ligger i User Trust Store.

Slik ser feilen ut

Hos dere avvises forbindelsen umiddelbart med en TLS- eller sertifikatfeil, og stasjonen kommer aldri fram til innlogging. Hos oss viser meglerloggen forsøket med årsaken «certificate unknown». Ser dere ett av disse, ligger ikke CA-en i User Trust Store, eller feil fil er importert — å prøve på nytt eller få utstedt nytt passord hjelper ikke.

Create the MQTT client

1. Broker address and port: from the sheet, exactly as written — not an IP address found elsewhere. The port is 8883; there is no unencrypted port.
2. TLS on, verifying the broker against the CA in the User Trust Store.
3. Username and password: from the sheet. The password was shown once when it was issued and cannot be read back — if it is lost, the building owner asks us for a new one.
4. Client id: your choice, unique per station.
5. Automatic reconnect on.
6. MQTT protocol version and keepalive: no requirement from us — the station's defaults are fine.

Connect and verify

With the CA installed and the credentials entered, the station should connect and stay connected: the broker accepts the login and the station can start publishing under its namespace. If it does not, the broker log on our side shows where it stopped — each stage has its own signature:

• No connection at all → nothing reaches us: network or firewall between the station and the internet, or a wrong address or port.
• "certificate unknown" on our side, a TLS or certificate error on yours → the CA is not in the User Trust Store, or the wrong file was imported (see above).
• "not authorised" → username or password. Check the sheet; a certificate re-import will not help here.
• Connected, but nothing arrives → a topic outside the building's namespace, or no point built and enabled yet.
• Connects and drops in a loop → tell us your client id; two stations sharing one id is one known cause.

To see our command topics in Workbench, run Discover on the MQTT device with the filter sites/<site_id>/c/#, or add one SubscribePoint on a known c/ topic and read its Read Value.

Publish under the building's namespace

Hvert bygg har sitt eget topic-område, sites/<site_id>/, der <site_id> er identifikatoren som står på tilkoblingsarket. Området har nøyaktig to undertrær, og tilgangsreglene i megleren håndhever retningen:

• sites/<site_id>/t/<point> — telemetri. Stasjonen publiserer hit og vi leser: målinger og faktisk satte verdier.
• sites/<site_id>/c/<point> — kommandoer. Vi publiserer settpunkter hit, og stasjonen abonnerer. Stasjonen skal ikke publisere hit.

The station's login writes only under sites/<site_id>/t/ and reads only under sites/<site_id>/c/. A subscription on a t/ topic receives nothing and shows no error. Anything outside the namespace of its own building is refused. Publish the full topic path — the sites/<site_id>/ prefix is part of the topic, not something we add on our side.

The MQTT driver offers eight point types: Boolean, Numeric, String and Enum, each as PublishPoint or SubscribePoint. A PublishPoint sends the station's value to us on t/. A SubscribePoint receives our value on c/.

A point's type cannot be changed after it is created. A point of the wrong type is deleted and created again.

Point naming suggestion: use the existing Niagara point name as <point> — ASCII letters, digits, hyphen and underscore, no spaces and no MQTT wildcards. For a writable point, the same <point> in both topics.

What we have seen work

Recommendations, not conditions. If your station does something else, tell us what — we adapt our side.

• The bare numeric value as text, for example 21.4 with a decimal point.
• On/off points as true and false, as Niagara sends them natively, or as 0 and 1. Tell us which points are on/off; the Type column of the export carries it.
• On every PublishPoint set Retained = true and Publish Message On Change = true, and check that each point has published once after the station connects. A point that has not changed since the station started is invisible to us until it does.
• QoS 1 or higher.
• No periodic re-publish is required.

Only if control is in scope

Whether we control anything in this building is agreed with the building owner, never assumed. When it is, the station subscribes under sites/<site_id>/c/<point> for each agreed setpoint — build the subscription only for points the owner has agreed we control.

Every value we publish on c/ is retained: a SubscribePoint shows it in Read Value the moment it is enabled. If Read Value stays empty, the Topic is wrong, the point is disabled, or we have not published on that topic yet — ask us.

On a SubscribePoint set: Topic = the full sites/<site_id>/c/<point>; Qo S = At Least Once (1) or Exactly Once (2); Local Point = the station point that holds the setpoint; Local Point Slot = the input your station uses for remote setpoints, never na. Alternatively leave Local Point empty and link the point's Out to the setpoint's input on the wire sheet.

The point list

Send us the Workbench export of the MQTT device's Points folder (columns Path, Navn or Name depending on Workbench language, Type, Out, Enabled, Local Point, Topic, Local Point Slot). We read every point from it; no separate list is needed. Rows that are placeholders (unnamed points, or points that reuse another point's topic) are kept and reported as duplicates when the owner uploads the file, so name them or leave them out.

A PublishPoint with Local Point = null publishes nothing. Every PublishPoint in the export must show a Local Point; a SubscribePoint either shows one or is wire-linked from Out.

If your tooling cannot export the point table, a semicolon-separated file with the columns TOPIC;ALIAS_NAME;NODE_FUNCTION;DESCRIPTION;DATAPOINT_TYPE works too: one row per topic, TOPIC with the t/ or c/ sub-root, NODE_FUNCTION "Read" or "Write" (a writable point is two rows with the same ALIAS_NAME), DATAPOINT_TYPE only for energy meters — "power" or "energy" — and empty otherwise.

Also tell us

• How points are sent: on change, or on a timer — and how often.
• Whether control is in scope for this building, and for which points.
• Anything on the station that can refuse or override a setpoint we send: interlocks, limits, local overrides.
• Optional: the public IP address the station connects from.
• Optional: whether this Niagara version trusts standard public certificate authorities without importing anything.

Information we must be precise about:

• site_id exactly as issued (topic prefix).
• Broker host, port 8883, CA certificate, login — from the connection sheet only.
• The point export — with Type filled for every row and Local Point filled for every PublishPoint.
• Which points are writable, agreed with the owner; for each, the two topics and the Local Point Slot used.
• Facets (units, precision) per numeric point, so limits and setpoints are interpreted in the right unit.

Etter at stasjonen er koblet til

On our side we check two separate things and report them separately: first, that the external door works — TLS and authentication succeed from outside; second, that your station is actually publishing — how many topics we receive. The first can be green while the second is still empty, which simply means the station has not published yet.

• Interruptions of some minutes happen during maintenance on our side; a station with automatic reconnect picks up by itself.
• Never disable certificate validation on the station. Over the internet that would let a third party read the login and command setpoints; the CA import above is the supported way.
• A station that worked for weeks and then stopped is trusting our server certificate instead of the CA — the fix is the CA import above, not a new password.