HTTP

Reference for the HTTP driver: polling HTTP and HTTPS endpoints as tags, credentials, path mapping, body parsing, PUT writes and types.

View as Markdown

The HTTP driver polls generic HTTP endpoints as tags: a LAN sensor with a tiny web server, a gateway that publishes readings at fixed URLs, a service of your own. It is the simplest client-mode driver in the product: Ganter Lab connects to the equipment with plain GET requests and reads each response body as one value.

Two properties draw the line around what it is for:

The transport is the device's own choice. A device reaches its service over TLS until its Send over plain HTTP tick says otherwise, and a host written with http:// or https:// in front of it moves that tick and is kept as the bare host, so the two can never disagree. Either way the driver sends the device's credential, a username and password as HTTP Basic or a bearer token, on every request. What the AVEVA PI and Redfish drivers still add for those two services is their vocabulary (PI paths and WebIds, Redfish resource trees), which this driver knows nothing about.
The whole response body is the value. The driver is not a JSON field extractor: a numeric tag expects the body to be the bare number.

Connection fields

Field	What it is	Format	Default
Host	The endpoint's host name or IP address. A host written with `http://` or `https://` in front of it moves the transport tick below to match and is stored without it. A port written after the host (`:8080`) goes to the Port field and a path after it (`/api`) to the Resource path, so a whole address such as `http://192.168.0.5:8080/api` can be pasted here. An IPv6 address keeps its brackets.	Host name, IP, or either with `http://` or `https://` in front	empty
Port	The TCP port. A new device leaves it empty, and an empty box means the port the chosen transport answers on, 443 over HTTPS and 80 in the clear: the box shows that port in grey and follows the transport tick, which is also how a device saved with 0 reads.	1 to 65535, or empty	empty
Resource path	An optional path prefix put in front of every tag's path, e.g. `api/v2`. Blank prefixes nothing.	path text	blank
Send over plain HTTP	Steps this one device down from HTTPS to clear HTTP. Off means HTTPS, which is what keeps a credential off the wire. The panel states the consequence: on plain HTTP the requests, and any credential the device carries, travel unencrypted. Use it for an endpoint that answers on no other transport.	on / off	off
Username	Account for HTTP Basic authentication, used only when no bearer token is set. Empty (with no token) leaves the requests anonymous.	Free text	empty
Password	The password paired with the username. Protected at rest per Windows user; a secret entered under another Windows account shows as unreadable and must be re-entered.	Free text	empty
Bearer token	A token sent as `Authorization: Bearer …` on every request. When set it wins over the username/password pair. Protected at rest the same way.	Token text	empty

On connect the driver verifies the endpoint with a HEAD request to the configured address, host plus resource path, falling back to GET when HEAD is not implemented; an address that answers either one successfully counts as reachable. A service whose root answers 404 while its API answers normally is therefore online, as long as the resource path points at the API. Over HTTPS the service's TLS certificate is accepted when Windows trusts it, or when you approved that very certificate under Equipment access on this driver's page. A credential on a device stepped down to plain HTTP travels unencrypted, and the station says so in the connector journal when the device connects. Each request is given ten seconds: an endpoint that accepts the connection and then says nothing costs one reading, not the whole device, because the other tags of the device are read in the same pass. The poll interval is configurable: the device default (1000 ms) applies to every tag that does not state its own.

Tag addressing

The tag's Path field is the URL path relative to the device's resource path:

Field	What it does	Values	Default
Path	The path requested for this tag. The full URL is `<transport>://<host>:<port>/<resource path>/<path>`.	Free text (required)	empty

Example: host 192.168.0.40 stepped down to plain HTTP, resource path api, tag path sensors/temp polls http://192.168.0.40/api/sensors/temp.

Reads

Each poll GETs the tag's URL and parses the entire response body by the tag's declared data type:

Type	Accepted body
Float	A number, invariant format (`21.5`, decimal point, no thousands separators)
Int32	An integer (`42`)
Boolean	`true` or `false`
String	Anything; the body is the value verbatim (a JSON document arrives as its raw text)

A body the declared type cannot parse, or a non-success status code, reads as a failed read: the tag goes to bad quality and its read-failure policy decides what is presented, as described on the Connector page. A non-success status is the endpoint refusing the read, and the tag's reason names the status and quotes what the endpoint said with it (HTTP 404 Not Found: …), in the same words as a refused write or command. A body the declared type cannot parse gives the tag a reason that quotes what could not be read, and the device stays connected. An endpoint that does not answer at all is the device's connection failing: the device reports it and reconnects, and its tags point to it. The tag's red line says such a status in the station's language, with what it means for 401, 403 and 404, and a body that does not parse as an answer that does not read as the tag's type; the Events page keeps the endpoint's own words.

Writes

Tags with a writable access mode write with PUT to the same URL: the body is the value as JSON, sent with content type application/json. A number goes as a bare literal (42.5), a boolean as true or false, and text goes quoted ("automatic"). The endpoint decides what to make of it; a non-success status is the endpoint refusing the value, and the refusal names the status and quotes what the endpoint said with it, in the same words as a refused command, so whoever wrote the value reads why. As everywhere else, the write box takes the engineering value and the tag's conversion stages are reversed before the raw value goes on the wire, as described on the Connector page.

Supported data types

Boolean, Int32, Float and String.

Commands

A tag reads a value; a command asks the service to do something. Declare each one on the device, in the Commands card of its page: a name, the path it is POSTed to (under the device's own address, exactly as a tag's path is), and optionally the name of the one value it takes. The row's Run verb sends it and reports what the service answered, and the command also becomes a method on the device in this station's own OPC UA address space, so anything that can call a method can issue it. The value you type is sent as the request body, as written.

What the service answers is the command's result. A status the service returns outside the success range is the service refusing the command, not the connection failing: the refusal names the status and quotes what the service said with it ("HTTP 500 Internal Server Error: the burner is locked out"), and nothing else on the device is disturbed by it.

Discovery

The driver has no discovery scan. Add each endpoint by host and each value by its path; the add-a-device flow is described on the Connector page.

Equipment access

An HTTPS endpoint with a self-signed certificate, or one issued by an authority of its own, presents a certificate no root installed in Windows vouches for. That root does not need to be installed on this computer. The first connection is refused, the device reads Waiting for certificate approval in the tree and on its page, whose Review certificate button opens this card on the certificate, and the certificate waits under Equipment access at the end of the HTTP driver's page, the same card the OPC UA driver's page carries, until you decide:

Group	What it lists	What you can do
Waiting for approval	Each refused certificate, under the name it claims: its SHA-256 fingerprint, the address it was met at, when it last tried and how many times, and its details (subject, issuer, domain names, validity dates). The one a device's Review certificate opened is marked Selected for review.	Approve accepts the certificate from the device's next connection attempt. Block keeps refusing it without listing it here again. Discard all pending certificates empties the list without approving or blocking anything.
Approved equipment	The certificates you approved or imported, with who decided and when, and the address each was last met at.	Withdraw approval closes the device's connection and returns its certificate to the list. Import certificate approves a public certificate file you already have (.der, .cer, .crt or .pem) before the first connection.
Blocked equipment	The certificates you blocked. A blocked certificate is refused even if Windows trusts it.	Unblock returns the certificate to the list, without approving it.

Check the fingerprint with whoever manages the equipment before you approve it. An approval accepts that certificate and no other, and only within its validity dates; it stands in for the root Windows lacks and for the name the certificate carries, so an endpoint dialed by its IP address connects although its certificate names another host, and nothing else about the certificate is relaxed. When the endpoint answers an address whose certificate you approved with another one, reading stops, the new one waits here, and the station raises "Certificate changed: <name>" with a Review button. A certificate Windows already trusts is accepted as before and never appears here; nothing is approved automatically. A device stepped down to plain HTTP presents no certificate and never waits here.

The driver's own failure says the reason instead of a nameless TLS error: "This equipment's certificate (the first 16 characters of the fingerprint) is waiting for your approval under Equipment access on the HTTP driver's page. Reading starts once you approve it." A blocked one reads "…is blocked at this station. Review it under Equipment access on the HTTP driver's page." A certificate outside its validity dates, revoked or with a broken signature is refused with that reason and is never listed, since no approval makes it sound.

The decisions are kept in the station's data folder, under ua\pki\http, and survive a restart. Only a role that may configure the Connector is drawn the verbs, and they act only in the station's own window: a browser on another device reads the card without changing it, and no agent tool approves a certificate (connector_browse reports the waiting device with awaitingCertificate). The list holds up to 100 certificates waiting for approval; once it is full, a new one is still refused but not listed, and the card says so.