Skip to content

feat: add face, brightnes and revision API. Add openAPI spec and postman collection - #287

Open
0m4r wants to merge 3 commits into
ktomy:mainfrom
0m4r:feat/add-more-api
Open

0m4r wants to merge 3 commits into
ktomy:mainfrom
0m4r:feat/add-more-api

Conversation

@0m4r

@0m4r 0m4r commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Description

This PR adds APIs for controlling the Nightscout Clock’s active face and display brightness, and adds the OpenAPI specification, tests, and Postman collection to match.

Changes Summary

1. Firmware: ServerManager.cpp

  • Added face management endpoints:
    • GET /api/faces — returns the active faces and their IDs and names
    • POST /api/face — selects a face by ID; requires {"face":"<id>"}. Returns {"status":"ok","face":"<id>"} on success
    • POST /api/face/next — advances to the next active face. Returns {"status":"ok"}
    • POST /api/face/prev — selects the previous active face. Returns {"status":"ok"}
  • Added brightness endpoints:
    • GET /api/brightness — returns the current brightness setting as {"value":<integer>}
    • POST /api/brightness/next — advances to the next brightness setting. Returns {"status":"ok"}
    • POST /api/brightness/prev — selects the previous brightness setting. Returns {"status":"ok"}
    • POST /api/brightness — sets brightness using {"value":<integer>}. Returns {"status":"ok"}
  • All endpoints require authentication when web authentication is enabled.
  • Invalid face IDs, malformed payloads, or unsupported brightness values return 400.
  • Display control is unavailable (returns 503) while the clock is in AP mode.

2. Display managers

  • Added face-listing (getActiveFaces), face selection (requestFace), and face stepping (requestNextFace, requestPreviousFace) in BGDisplayManager.
  • Added brightness stepping (requestBrightnessStep, requestPreviousBrightnessStep) and direct brightness selection (requestBrightnessValue) in DisplayManager.
  • Direct brightness values support 1–10 for manual settings, 100 for linear auto, and 101 for dimmed auto.

3. OpenAPI spec: openapi.yaml (new file)

  • Documents the face and brightness endpoints, request payloads, and responses.
  • Simulated button routes are intentionally excluded; they are not part of the public API.

4. Tests: test/test_openapi.mjs (new file)

  • Added endpoint checks for the face and brightness APIs and the specification.
  • Asserts documented paths and methods, request/response details, authentication behavior, and that excluded routes are absent from the spec.

5. Supporting files

  • scripts/NightscoutClock.postman_collection.json (new file): Postman collection for manual API exploration.
  • web/build.mjs: emits the OpenAPI spec into the LittleFS filesystem image.
  • AGENTS.md: documents OpenAPI spec maintenance rules.

API Behavior

Endpoint Method Payload Success response
/api/faces GET None 200 JSON array of {id, name}
/api/face POST {"face":"<id>"} 200 {"status":"ok","face":"<id>"}
/api/face/next POST None 200 {"status":"ok"}
/api/face/prev POST None 200 {"status":"ok"}
/api/brightness GET None 200 {"value":<integer>}
/api/brightness/next POST None 200 {"status":"ok"}
/api/brightness/prev POST None 200 {"status":"ok"}
/api/brightness POST {"value":<integer>} 200 {"status":"ok"}
  • Returns: HTTP 400 for an invalid face ID, malformed payload, or unsupported brightness value; HTTP 503 if display control is unavailable in AP mode
  • Authentication: Required when web authentication is enabled
  • Brightness values: 1–10 manual, 100 linear auto, 101 dimmed auto

Testing

  • OpenAPI endpoint tests were added in test/test_openapi.mjs.
  • run_tests.sh and the firmware build (scripts/build.sh) should be run before opening the PR, and the change should be validated on a real device before merging.

0m4r added 3 commits November 19, 2026 09:08
Add HTTP endpoints for selecting and navigating clock faces and adjusting
display brightness: GET /api/faces, POST /api/face, POST /api/face/next,
POST /api/face/prev, GET /api/brightness, POST /api/brightness/next,
POST /api/brightness/prev, POST /api/brightness. All endpoints require
authentication when web authentication is enabled and return 400 on
invalid input. Document the endpoints in openapi.yaml, add host-side
tests in test/test_openapi.mjs, and provide a Postman collection for
manual API exploration.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant