Display POST

Set data for the displayController.

URL : /api/display/
Method : POST
Auth required : CONDITIONAL (see "Authentication")

Example Body

{
  "indicators": {
    "1": true,
    "2": false
  },
  "tubes": {
    "1": {
      "val": 1,
      "pwm": 255
    },
    "2": {
      "val": 1,
      "pwm": 255
    }
  },
  "onboardLed": {
    "pwm": 255,
    "mode": 0,
    "blinkAmount": 0
  },
  "leds": 255,
}

Usage

This endpoint only accepts POST requests using the application/json content header.
Failure to provide this header will result in a 404 response.

Not all parameters must be supplied when POSTing to the endpoint.
Only the parameters specified in your body will be changed.

There is no way to "clear" settings as the system will either supplement them with fallback values or just ignore them altogether.

Parameters

Below is a list of all parameters that can be presented in the request body:

tubes

Controls the IN-4 tubes.

Payload

"tubes": {
  "<tubeIndex>": {
    "val": <int>,
    "pwm": <int>
  }
}

• tubeindex(int)
  • Which tube to address (left to right).
    • Must be between 1 and 4.
• val(int)
  • The number to display on the tube.
    • If this number exceeds 9, the tube will be turned off instead.`.
• pwm (int)
  • Brightness of the tube.
    • Must be an 8-bit number whereas 255 is the maximum.

indicators

Controls the INS-1 tubes.

Payload

"indicators": {
  "<indicatorIndex>": <state>
}

• indicatorIndex (int)
  • Which indicator tube to address (left to right).
    • Must be either 1 or 2.
• state (bool)
  • If the indicator should light up or not.
    • true > turn on
    • false > turn off

onboardLed

Controls the onboard LED next to the ESP32.

Payload

"onboardLed": {
  "pwm": <int>,
  "mode": <int>,
  "blinkAmount": <int>
}

• pwm (int)
  • Brightness of the LED.
    • Must be an 8-bit number whereas 255 is the maximum.
• mode (int)
  • Behavior of the LED.
    • 0 > Steady light
    • 1 > Blinking (Off -> On)
    • 2 > Blinking (On -> Off)
    • 3 > Pulsate
  • If mode is neither of these values, it will default to mode 0.
• blinkAmount (int)
  • Amount of times the LED should blink.
    • Must be between 1 and 8.
    • Only applicable if mode is set to 2 (blinking).

leds

Controls the LEDs beneath the IN-4 tubes.

Payload

"leds": <pwm>

• pwm (int)
  • Brightness of the LEDs.
    • Must be an 8-bit number whereas 255 is the maximum.

Authentication

This endpoint has a conditional authentication mechanism:
To authenticate, supply an auth code using the auth URI-parameter, like so:
http://.../api/endpoint?auth=<authcode>

The authentication code must be a number larger than 0 and may not exceed the 32 bit integer limit.

• Authentication is only required if an authentication code has been set.
  • Initially, meaning at system boot, no code will be set.
  • The first call with the auth URI parameter, successful or not, will set an immutable authentication code.
  • To clear the authentication code, the system must be rebooted again.
  • To see whether authentication is required or not, perform a GET on /api/display, checking for the value of the authRequired property.

ℹ️ The intent of this auth mechanism is not to offer "true" security, but rather to prevent multiple devices from accessing the display simultaneously.

Invalid authentication attempts will return a 403 response.

Error handling

The whole request body gets validated once received by the system.
If a parameter or value violates the authentication set as dictated by the system, the whole request gets discarded and will instead return a 400 response.