Skip to content

HTTPS (device UI + REST API)

OWTS serves the device UI (SPA from SPIFFS) and the REST API over HTTPS to avoid leaking future credentials (Bearer token) on the local network.

This is implemented with ESP-IDF’s esp_https_server (built on esp_http_server): HTTPS Server docs.

Ports and behavior

  • HTTPS: :443
    • Serves the full UI (/) and REST API (/api/*).
  • HTTP: :80
    • Serves redirects only (HTTP 302) to the equivalent https://… URL.
    • Purpose: give users a simple entrypoint (http://…) and get them onto HTTPS.

Certificate model (dev / local)

OWTS uses a self-signed certificate embedded into the firmware build (main/web/owts.crt, main/web/owts.key).

  • Trust: browsers will show a warning because the certificate is self-signed. This is expected in this project.
  • Name matching: the certificate is generated with:
    • IP:192.168.4.1 for SoftAP access, and
    • DNS:*.local to match device mDNS hostnames like OWTS-winch-<esp_id>.local and OWTS-aircraft-<esp_id>.local.

Generating / rotating certificates

Helper script (run from main/web/):

  • ./gen_certs.sh
    • default validity: 3650 days (press Enter)
    • optionally regenerates owts.key
    • always re-issues owts.crt

After regenerating, rebuild and flash the firmware (the PEMs are embedded via ESP-IDF EMBED_TXTFILES).

mDNS advertisement

OWTS advertises both services via mDNS:

  • _http._tcp on port 80
  • _https._tcp on port 443

The device hostname is derived from mode + device ID, e.g. OWTS-winch-<esp_id>.local.

Known TLS handshake logs

You may see occasional TLS handshake failures in the ESP logs like: mbedtls_ssl_handshake returned -0x7780.

This can happen when clients/browsers abort speculative connections or when a client refuses a certificate during the warning flow. If the UI/API works after accepting the warning, these sporadic messages are typically harmless.

mbedtls_ssl_setup returned -0x7F00 / ESP_ERR_MBEDTLS_SSL_SETUP_FAILED

-0x7F00 is MBEDTLS_ERR_SSL_ALLOC_FAILED: the device ran out of internal RAM while creating another TLS session. It is common when a phone browser (especially Safari on iOS) opens several HTTPS connections at once — page load, API polling, speculative tabs — while OWTS also runs WiFi, radio, and sensor tasks. PSRAM is not enabled in the default sdkconfig.defaults.

Mitigations in-tree:

  • CONFIG_MBEDTLS_DYNAMIC_BUFFER and a smaller CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN (8 KiB) in sdkconfig.defaults
  • HTTPS max_open_sockets = 4 with lru_purge_enable in owts_web.c. REST, file, and redirect handlers send Connection: close and drop the session after the body, so those sockets are not held for the 10 s receive timeout
  • At most two live wss:// sockets (GET /api/live). The page opens one only while a monitor view is on screen and the tab is visible (aircraft live page, or the winch home page). A further live client is closed. The socket pushes a snapshot when IAS/phase or the winch revision changes. Logs and settings stay REST
  • The hardware-error banner is the only client of GET /api/hw/errors. It polls at most every 30 seconds, and each poll is still one TLS handshake

If failures persist after a rebuild/flash:

  • Close extra Safari tabs to the device; reload once
  • Prefer one monitoring page at a time
  • Check logs for heap / minimum free around the errors
  • As a last resort, enable SPIRAM in menuconfig (hardware must have PSRAM)