Receive data from devices in your space and publish them as part of your SpaceAPI JSON :3
Find a file
2024-08-03 22:18:47 +02:00
config docs: Improve log output for missing config 2024-08-03 22:18:47 +02:00
handlers feat: Add support for PUT/DELETE state.message 2024-08-03 19:50:19 +02:00
persistence feat: Add support for PUT/DELETE state.message 2024-08-03 19:50:19 +02:00
types feat: Add support for PUT/DELETE state.message 2024-08-03 19:50:19 +02:00
util Refactor environment sensor URL path generation 2024-05-26 20:52:23 +02:00
.gitignore Rename config shards in .gitignore 2024-05-26 20:52:18 +02:00
config-template.json Location is optional for beverage_supply so make it omitempty 2024-05-26 20:52:22 +02:00
go.mod refactor: Add Go 1.22 HTTP method matching 2024-08-03 17:55:28 +02:00
LICENSE Add BSD-3-Clause LICENSE 2023-11-04 21:07:40 +01:00
main.go docs: Update README and code comments 2024-08-03 21:02:44 +02:00
README.md refactor!: Change config path env var name 2024-08-03 22:18:41 +02:00

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