spaceapid/README.md

2.4 KiB

SpaceAPI Daemon

spaceapid serves a SpaceAPI-compatible JSON on port 8080:

$ curl http://localhost:8080 | jq
{
  "api_compatibility": [
    "14"
  ],
  "space": "CCCHH",
  ...
}

Configuring

spaceapid has to be configured via one or multiple json files. A sample configuration is provided as config-template.json. The config consists of three parts:

  • "credentials"
    • List of Username/Password credentials for HTTP BasicAuth
  • "dynamic"
    • The configuration for the dynamic parts of the message
  • "response"
    • The static (pre-filled) parts of the response

See Running for details.

Building

See the go.mod file for minimum required Go version. There are currently no dependencies apart from the Go standard library.

go build -ldflags '-X main.version=v420.69-rc23' .

Running

Set the environment variable to a comma-separated list of config files or pass the -c flag.

env CONFIG_PATH=config-template.json go run .
# OR
go run . -c config-credentials.json,config-dynamic.json,config-response.json

Updating values

The state of the boolean state->open and state->message property can be modified via /state/{open,message}:

curl -X PUT -u user:password -d true http://localhost:8080/state/open
curl -X PUT -u user:password -d "Nur mit Passierschein A38 :3" http://localhost:8080/state/message

As state->message is optional, its value can be deleted by using the PUT method with an empty payload, or by using DELETE:

curl -X PUT -u user:password -d "" http://localhost:8080/state/message
# OR
curl -X DELETE -u user:password http://localhost:8080/state/message

The same updating procedure applies for the endpoints for sensors configured under "dynamic". Currently only the sensors with the value/unit/location/name/description schema are implemented. At the time of writing this includes temperature, barometer, humidity, beverage_supply, power_consumption, and account_balance. Out-of-spec sensors may be used as well, as long as they share the same schema.

curl -X PUT -u user:password -d 23.42 http://localhost:8080/sensors/{temperature,humidity,...}[/location[/name]]

As can be seen in the example, the http urls are generated from sensor type and optionally location and name. Depending on sensor type, location might be required for your sensors, see the schema for details.