= netzteil-http(7)
:doctype: manpage
:man source: opennetzteil
== Name
netzteil-http - a programming interface for power supplies over http
== Description
OpenNetzteil provides a uniform HTTP API for powersupplies to be controlled over HTTP.
Usually, these devices can be controlled over a device specific and loosely specified protocol called SCPI.
Such powersupplies are accessed differently, some possibilities are USB, TCP, Serial Line, …
The HTTP API, described in this document, aims to be a proxy which can be used to run even multiple, different power supplies on one machine.
Authentication, authorization, and other security mechanism are not in the scope of this API.
Use a reverse proxy for implementing more sophisticated HTTP techniques.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
== Data Format
The API exclusively uses data encoded in the JSON format (RFC7159).
The data is encoded in the most minimal way.
For instance, an endpoint delivering a float value encodes this as a plain JSON float: `10.501`.
No dictionary or more complex data structures are needed.
The data type of each endpoint in this specification is mentioned in the appropriate endpoint description.
An exception to this rule are the `…/voltage/ws`, `…/current/ws`, and `…/measurements/ws` endpoints.
In order to unify these three interfaces, the returned data looks like the following:
----
{
"voltage":10.100000381469727,
"current":5,
"time":"2020-05-19T23:41:46.305841551+02:00"
}
----
Empty keys SHOULD be omitted.
The `time` key is REQUIRED.
== API
Every GET endpoint delivers data encoded in JSON.
Every PUT endpoint accepts data encoded in JSON.
If there is only one device available, a reduces API MAY be provided by implementations.
All endpoints MUST be prepended the opennetzteil namespace indicator: `/_netzteil/api/`.
The full path of the `/devices` endpoint looks like the following: `/_netzteil/api/devices`.
Some endpoints include the wording “points to …”.
This endpoint MAY use an HTTP 308 redirect to the appropriate, pointed endpoint.
The API using redirects to other endpoints is called reduced API.
The `|` sign indicates a logical `or`.
GET|PUT (OPTIONAL) `/device`::
If **only one** device is served, this endpoint points to `/devices/0/…`.
GET (REQUIRED) `/devices`::
Query the available power supplies.
GET (REQUIRED) `/devices/{id}/out`::
Query the status of the master output.
Returns a boolean JSON body: `true`, or `false`.
PUT (REQUIRED) `/devices/{id}/out`::
Set the status of the master output.
Accepts a boolean JSON body: `true`, or `false`.
GET (REQUIRED) `/devices/{id}/ident`::
Returns the device identity.
Typically, this is the model name, e.g. `RND 320-KD3005P V2.0`.
GET (OPTIONAL) `/devices/{id}/raw/ws`::
Grab a websocket exposing a raw connection to the device.
Custom commands (not exposed by this HTTP API) can be accessed via this endpoint.
PUT (OPTIONAL) `/devices/{id}/beep`::
TODO
GET (OPTIONAL) `/devices/{id}/status`::
Query status information.
The returned data is device specific, it is RECOMMENDED to use a JSON dict with descriptive keys.
GET|PUT (OPTIONAL) `/devices/{id}/channel`::
If the device has *only one* channel, this endpoint points to `/devices/{id}/channels/0`.
GET (REQUIRED) `/devices/{id}/channels`::
Returns the number of available channels.
Returns an integer value.
GET (REQUIRED) `/devices/{id}/channels/{channel}/current`::
Returns the present current in `A`.
Returns a float value.
PUT (REQUIRED) `/devices/{id}/channels/{channel}/current`::
Sets the maximum current `A`.
Accepts a float value.
GET (REQUIRED) `/devices/{id}/channels/{channel}/voltage`::
Returns the present voltage in `V`.
Returns a float value.
PUT (REQUIRED) `/devices/{id}/channels/{channel}/voltage`::
Sets the maximum voltage `V`.
Accepts a float value.
GET (OPTIONAL) `/devices/{id}/channels/{channel}/voltage/ws?interval={ms}`::
TODO
GET (OPTIONAL) `/devices/{id}/channels/{channel}/current/ws?interval={ms}`::
TODO
GET (OPTIONAL) `/devices/{id}/channels/{channel}/measurements/ws?interval={ms}`::
TODO
GET (REQUIRED) `/devices/{id}/channels/{channel}/out`::
Query the status of the channel `channel` of device with the id `id`.
Returns a boolean value.
PUT (REQUIRED) `/devices/{id}/channels/{channel}/out`::
Sets the status of the channel `channel` of device with the id `id`.
Accepts a boolean value.
GET (REQUIRED) `/devices/{id}/channels/{channel}/ocp`::
TODO
PUT (REQUIRED) `/devices/{id}/channels/{channel}/ocp`::
TODO
GET (REQUIRED) `/devices/{id}/channels/{channel}/ovp`::
TODO
PUT (REQUIRED) `/devices/{id}/channels/{channel}/ovp`::
TODO
== Authors
Maintained by Stefan Tatschner <stefan@rumpelsepp.org>.
The Git repository is hosted here: https://git.sr.ht/~rumpelsepp/opennetzteil
== License
This document published under the Attribution-ShareAlike 4.0 International license.
The license text is availabe here: https://creativecommons.org/licenses/by-sa/4.0/