Skip to content

Latest commit

 

History

History
139 lines (98 loc) · 5.58 KB

netzteil-http.7.adoc

File metadata and controls

139 lines (98 loc) · 5.58 KB
Raw

netzteil-http(7) Manual Page

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 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).

GET|PUT (OPTIONAL) /device

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

TODO

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}

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

Maintainer

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/