~rumpelsepp/homepage

a91b43014335eab2afc93cda22046d2c5cfdfa06 — Stefan Tatschner 10 months ago beca52f
Add specifications written by me
6 files changed, 177 insertions(+), 15 deletions(-)

M Gemfile.lock
M _config.yml
A _layouts/specs.html
A _specs/netzteil-http.7.adoc
M manage.sh
A specs.adoc
M Gemfile.lock => Gemfile.lock +10 -8
@@ 14,7 14,7 @@ GEM
    eventmachine (1.2.7)
    ffi (1.12.2)
    forwardable-extended (2.6.0)
    html-proofer (3.15.2)
    html-proofer (3.15.3)
      addressable (~> 2.3)
      mercenary (~> 0.3)
      nokogumbo (~> 2.0)


@@ 25,7 25,7 @@ GEM
    http_parser.rb (0.6.0)
    i18n (1.8.2)
      concurrent-ruby (~> 1.0)
    jekyll (4.0.0)
    jekyll (4.0.1)
      addressable (~> 2.4)
      colorator (~> 1.0)
      em-websocket (~> 0.5)


@@ 49,7 49,8 @@ GEM
      sassc (> 2.0.1, < 3.0)
    jekyll-watch (2.2.1)
      listen (~> 3.0)
    kramdown (2.1.0)
    kramdown (2.2.1)
      rexml
    kramdown-parser-gfm (1.1.0)
      kramdown (~> 2.0)
    liquid (4.0.3)


@@ 65,18 66,19 @@ GEM
    parallel (1.19.1)
    pathutil (0.16.2)
      forwardable-extended (~> 2.6)
    public_suffix (4.0.4)
    public_suffix (4.0.5)
    rainbow (3.0.0)
    rb-fsevent (0.10.3)
    rb-fsevent (0.10.4)
    rb-inotify (0.10.1)
      ffi (~> 1.0)
    rouge (3.17.0)
    rexml (3.2.4)
    rouge (3.19.0)
    safe_yaml (1.0.5)
    sassc (2.2.1)
    sassc (2.3.0)
      ffi (~> 1.9)
    terminal-table (1.8.0)
      unicode-display_width (~> 1.1, >= 1.1.1)
    typhoeus (1.3.1)
    typhoeus (1.4.0)
      ethon (>= 0.9.0)
    unicode-display_width (1.7.0)
    yell (2.2.2)

M _config.yml => _config.yml +7 -0
@@ 19,10 19,17 @@ defaults:
      type: "stuff"
    values:
      layout: page
  - scope:
      path: ""
      type: "specs"
    values:
      layout: page

collections:
  stuff:
    output: true
  specs:
    output: true

# Build settings
plugins:

A _layouts/specs.html => _layouts/specs.html +14 -0
@@ 0,0 1,14 @@
---
layout: default
---

  <h2>Specs</h2>

  <ul class="post-list">
    {% for item in site.specs %}
      <li>
        <a href="{{ item.url }}">{{ item.title }}</a>
      </li>
    {% endfor %}
  </ul>


A _specs/netzteil-http.7.adoc => _specs/netzteil-http.7.adoc +128 -0
@@ 0,0 1,128 @@
= 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.

== API

This API is also called the complete API.
Every GET endpoint delivers data encoded in JSON (RFC7159).
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 endpoint path of the `/devices` endpoint looks like the following: `/_netzteil/api/devices`.

GET `/devices`::
    Query the available power supplies.

GET `/devices/{id}/out`::
    TODO

PUT `/devices/{id}/out`::
    `true`

GET `/devices/{id}/ident`::
    TODO

PUT `/devices/{id}/beep`::
    TODO

GET `/devices/{id}/channels`::
    TODO

GET `/devices/{id}/channels/{channel}/current`::
    TODO

PUT `/devices/{id}/channels/{channel}/current`::
    TODO

GET `/devices/{id}/channels/{channel}/voltage`::
    TODO

PUT `/devices/{id}/channels/{channel}/voltage`::
    `10.45`

GET `/devices/{id}/channels/{channel}/out`::
    TODO

PUT `/devices/{id}/channels/{channel}/out`::
    TODO

GET `/devices/{id}/channels/{channel}/ocp`::
    TODO

PUT `/devices/{id}/channels/{channel}/ocp`::
    TODO

GET `/devices/{id}/channels/{channel}/ovp`::
    TODO

PUT `/devices/{id}/channels/{channel}/ovp`::
    TODO

== Reduced API

The reduced API is optional if **only one** device is served via an opennetzteil application.
The reduced API MAY be implemented using an HTTP 308 redirect to the appropriate endpoint of the complete API.
If two or more devices are served, all endpoints of the reduced API MAY return a 404 error.
If no 308 redirects are used, the responses MUST be served directly from the reduced API.
All endpoints MUST be prepended the opennetzteil namespace indicator: `/_netzteil/api/`.

GET `/device/out`::
    TODO

PUT `/device/out`::
    `true`

GET `/device/ident`::
    TODO

PUT `/device/beep`::
    TODO

GET `/device/channels`::
    TODO

GET `/device/channels/{channel}/current`::
    TODO

PUT `/device/channels/{channel}/current`::
    TODO

GET `/device/channels/{channel}/voltage`::
    TODO

PUT `/device/channels/{channel}/voltage`::
    `10.45`

GET `/device/channels/{channel}/out`::
    TODO

PUT `/device/channels/{channel}/out`::
    TODO

GET `/device/channels/{channel}/ocp`::
    TODO

PUT `/device/channels/{channel}/ocp`::
    TODO

GET `/device/channels/{channel}/ovp`::
    TODO

PUT `/device/channels/{channel}/ovp`::
    TODO

M manage.sh => manage.sh +13 -7
@@ 89,6 89,11 @@ deploy() {
    rsync -e "ssh -o VerifyHostKeyDNS=yes -o StrictHostKeyChecking=accept-new" -rP --delete "_site/" deploy@batuu.sevenbyte.org:rumpelsepp.org/
}

update_specs() {
    cd _specs
    curl -LOs "https://git.sr.ht/~rumpelsepp/opennetzteil/blob/master/man/netzteil-http.7.adoc"
}

while getopts "h" opt; do
    case $opt in
        n)    shift && NOEDITOR=1;;


@@ 100,11 105,12 @@ done
shift $((OPTIND - 1))

case $1 in
    new-post)   shift && post_create      && exit 0;;
    upload)     shift && upload      "$@" && exit 0;;
    build)      shift && build       "$@" && exit 0;;
    serve)      shift && serve       "$@" && exit 0;;
    test-links) shift && test_links       && exit 0;;
    deploy)     shift && deploy           && exit 0;;
    *)          usage                     && exit 1;;
    new-post)     shift && post_create      && exit 0;;
    upload)       shift && upload      "$@" && exit 0;;
    build)        shift && build       "$@" && exit 0;;
    serve)        shift && serve       "$@" && exit 0;;
    test-links)   shift && test_links       && exit 0;;
    deploy)       shift && deploy           && exit 0;;
    update-specs) shift && update_specs     && exit 0;;
    *)            usage                     && exit 1;;
esac

A specs.adoc => specs.adoc +5 -0
@@ 0,0 1,5 @@
---
layout: specs
---

= Specs