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/