docs: Update README and code comments

This commit is contained in:
Bendodroid 2024-08-03 21:02:44 +02:00
parent 68d0ec05db
commit 5dacfd0dfe
2 changed files with 34 additions and 23 deletions

View file

@ -3,7 +3,7 @@
`spaceapid` serves a [SpaceAPI](https://spaceapi.io)-compatible JSON on port 8080:
```shell
$ curl http://[::1]:8080 | jq
$ curl http://localhost:8080 | jq
{
"api_compatibility": [
"14"
@ -28,26 +28,6 @@ The config consists of three parts:
See [Running](#Running) for details.
## Updating values
The state of the boolean `state->open` property can be modified via `/state/open`:
```shell
curl -X PUT -u user:password -d true http://[::1]:8080/state/open
```
The same is true 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.
```shell
curl -X PUT -u user:password -d 23.42 http://[::1]: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.
## Building
See the `go.mod` file for minimum required Go version.
@ -62,3 +42,32 @@ 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}`:
```shell
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`:
```shell
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.
```shell
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.

View file

@ -50,20 +50,22 @@ func main() {
os.Exit(0)
}(&conf.Response)
// Register HTTP handlers
// Root handler
http.HandleFunc("GET /{$}",
handlers.Root(&conf.Response),
)
// state->open
http.HandleFunc("PUT /state/open",
handlers.StateOpen(conf.Credentials, conf.Dynamic.State.Open.AllowedCredentials, &conf.Response.State),
)
// state->message
http.HandleFunc("PUT /state/message",
handlers.StateMessagePUT(conf.Credentials, conf.Dynamic.State.Open.AllowedCredentials, &conf.Response.State),
)
http.HandleFunc("DELETE /state/message",
handlers.StateMessageDELETE(conf.Credentials, conf.Dynamic.State.Open.AllowedCredentials, &conf.Response.State),
)
// Register handler for environmental sensors
// Register handlers for environmental sensors
for sensorType, envSensorConfigs := range conf.Dynamic.Sensors {
for i, envSensorConfig := range envSensorConfigs {
urlPattern := "PUT " + util.GetSensorURLPath(