periph-web

README

periph-web

Web UI and JSON API server for periph.io.

• The web UI doesn't depend on external web resources, so it can be used on networks without internet access!
• The Go code doesn't depend on any external library besides the Go standard library.

Try it now:

go get -u periph.io/x/periph/experimental/cmd/periph-web
periph-web

API

periph-web exposes a JSON API to enable the web UI:

Getters (read only, no side effect):

• /api/periph/v1/gpio/aliases: returns GPIO aliases in gpioreg.
• /api/periph/v1/gpio/list: returns all registered GPIOs in gpioreg, even the ones not on board headers (pinreg).
• /api/periph/v1/header/list: returns all registered headers in pinreg.
• /api/periph/v1/i2c/list: returns all registered I²C buses in i2creg.
• /api/periph/v1/spi/list: returns all registered SPI ports in spireg.
• /api/periph/v1/server/state: returns the loaded periph drivers.

Actions:

• /api/periph/v1/gpio/read: accepts a list of GPIO names and return their gpio.Level as 0 or 1.
• /api/periph/v1/gpio/out: sets the output of GPIOs specified as a dict of {gpio pin name: level at 0 or 1}.
• /raw/periph/v1/xsrf_token: returns a fresh XSRF token as a raw string. This is not a JSON API.

Using with curl

The API is protected via a XSRF token. It is valid for 24 hours and needs to be refreshed. Request without a token will be denied with 401.

Here's how to access the HTTP JSON API via bash:

export TARGET_HOST=raspberrypi:7080
export XSRF_TOKEN="$(curl -s -X POST http://$TARGET_HOST/raw/periph/v1/xsrf_token)"
curl -s -b "XSRF-TOKEN=$XSRF_TOKEN" -d '{}' -H Content-Type:application/json http://$TARGET_HOST/api/periph/v1/header/list | python -mjson.tool

Read the values of GPIO5 and GPIO6:

curl -s -b "XSRF-TOKEN=$XSRF_TOKEN" -d '["GPIO5","GPIO6"]' -H Content-Type:application/json http://$TARGET_HOST/api/periph/v1/gpio/read

Set the GPIO6 as output to High:

curl -s -b "XSRF-TOKEN=$XSRF_TOKEN" -d '{"GPIO6":1}' -H Content-Type:application/json http://$TARGET_HOST/api/periph/v1/gpio/out

By default, the HTTP server binds to localhost. If you want to access it from another host, pass the argument -http=0.0.0.0:7080 or the port of your choosing.

Live reload

To use the files in static/ instead of the ones embedded in the executable by go generate, use:

go install -tags debug periph.io/x/periph/experimental/cmd/periph-web

Extended support

If you want to play with a FTDI FT232H/FT232R, you have to build with periph.io/x/extra built in. You can do with:

go get -u -tags periphextra periph.io/x/periph/experimental/cmd/periph-web

Cross-compiling won't work with extra.

Documentation

Overview

periph-web runs a web server exposing periph's state.