A specification and an implementation for controlling power supplies via http
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.6 KiB


netzteil-http - a programming interface for power supplies over http


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:


Empty keys SHOULD be omitted. The time key is REQUIRED.


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 and any endpoint matching the path prefix MAY use an HTTP 308 redirect to the appropriate, pointed endpoint. For instance, if only one device is registered, /device is available and points to /devices/0. In this case, a request to /device/channels/5/current is redirected to /devices/0/channels/5/current.

The | sign indicates a logical or. Return values are indicated with an arrow , parameters via e.g. PUT are in brackets, e.g. (bool).


If only one device is served, this endpoint points to /devices/0/….

GET (REQUIRED) /devices → string

Query the available power supplies.

GET (REQUIRED) /devices/{id}/out → bool

Query the status of the master output.

PUT (REQUIRED) /devices/{id}/out (bool)

Set the status of the master output. Accepts a boolean JSON body: true, or false.

GET (REQUIRED) /devices/{id}/ident → string

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


GET (OPTIONAL) /devices/{id}/status → dict

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 → int

Returns the number of available channels.

GET (REQUIRED) /devices/{id}/channels/{channel}/current → float

Returns the present current in A.

PUT (REQUIRED) /devices/{id}/channels/{channel}/current (float)

Sets the maximum current in A.

GET (REQUIRED) /devices/{id}/channels/{channel}/voltage → float

Returns the present voltage in V.

PUT (REQUIRED) /devices/{id}/channels/{channel}/voltage (float)

Sets the maximum voltage V.

GET (OPTIONAL) /devices/{id}/channels/{channel}/voltage/ws?interval={ms}


GET (OPTIONAL) /devices/{id}/channels/{channel}/current/ws?interval={ms}


GET (OPTIONAL) /devices/{id}/channels/{channel}/measurements/ws?interval={ms}


GET (REQUIRED) /devices/{id}/channels/{channel}/out → bool

Query the status of the channel channel of device with the id id.

PUT (REQUIRED) /devices/{id}/channels/{channel}/out (bool)

Sets the status of the channel channel of device with the id id.

GET (REQUIRED) /devices/{id}/channels/{channel}/ocp → bool

Returns the state of the OverCurrentProtection.

PUT (REQUIRED) /devices/{id}/channels/{channel}/ocp (bool)

Sets the state of the OverCurrentProtection.

GET (REQUIRED) /devices/{id}/channels/{channel}/ovp → bool

Returns the state of the OverVoltageProtection.

PUT (REQUIRED) /devices/{id}/channels/{channel}/ovp (bool)

Sets the state of the OverVoltageProtection.



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/