~rumpelsepp/homepage

ref: 2a0829d7d5c82198e590e856efc864471be97a18 homepage/_specs/netzteil-http.7.adoc -rw-r--r-- 5.2 KiB
2a0829d7 — Stefan Tatschner add degoogle | A huge list of alternatives to Google products. Privacy tips, tricks, and links. 4 months ago 
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
= 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/