Skip to content

web-ui-api.md

Latest commit

 

History

History
87 lines (69 loc) · 2.93 KB

web-ui-api.md

File metadata and controls

87 lines (69 loc) · 2.93 KB

Web UI & REST API

Server Architecture

  • Router: gorilla/mux, strict slash
  • Middleware: GZIP, CORS (*), ETag caching, request logging, JSON headers, JWT auth
  • Timeouts: Read 5s, Write 10s, Idle 120s
  • Static assets: embedded in binary (fs.FS)
  • Default port: 7070

REST API (base /api/)

Site-level

  • POST /buffersoc/{value}, /prioritysoc/{value}, /residualpower/{value} etc.
  • GET /tariff/{tariff} — tariff rates
  • GET /sessions — charging history
  • GET /state — complete system state (supports jq filtering)

Per-loadpoint (/loadpoints/{id}/...)

  • POST mode/{value} — off/now/minpv/pv
  • POST limitsoc/{value}, limitenergy/{value} — charge limits
  • POST mincurrent/{value}, maxcurrent/{value} — current limits
  • POST phases/{value} — phase config
  • POST priority/{value}, batteryboost/{value}
  • POST plan/energy/{value}/{time} — schedule plan
  • POST vehicle/{name} — select vehicle
  • POST smartcostlimit/{value} — smart cost threshold

Configuration (/config/..., auth required)

  • CRUD for devices (chargers, meters, vehicles, tariffs)
  • Template browsing and testing
  • Site, loadpoint, circuit, HEMS, messaging config
  • GET /config/evcc.yaml — YAML export

System (/system/..., auth required)

  • Log viewing, cache clear, DB backup/restore/reset, shutdown

Handler Pattern

Generic handler[T] with type conversion, setter, getter. Specialized: floatHandler, intHandler, boolHandler, durationHandler.

WebSocket (/ws)

  • coder/websocket (RFC 6455)
  • Pub/sub via SocketHub
  • Buffered channels (1024 per subscriber)
  • Welcome message with full state snapshot
  • Incremental updates as JSON key-value pairs with dot-notation keys: 
    {"loadpoints.1.mode": "solar", "site.gridPower": 1234}
  • Write timeout: 10s, compression (disabled for Safari)

State Flow

  1. WS connects -> receives welcome with full state
  2. App emits util.Param on changes
  3. Hub broadcasts to subscribers
  4. Frontend store.update(msg) merges via dot-notation
  5. Components reactively re-render

Authentication

  • JWT, 90-day lifetime
  • HttpOnly cookie (auth) with SameSite=Strict
  • Also accepts Authorization: Bearer <token> header
  • Modes: Disabled, Locked (demo), Configured (password)
  • Protects /api/config and /api/system

MQTT Integration

  • Publishes state changes to configurable broker
  • Subscribes to control topics
  • Retained messages for state persistence

Key Files

  • server/http.go — router setup
  • server/http_auth.go — authentication
  • server/http_site_handler.go — state + request handlers
  • server/http_config_*.go — config endpoints
  • server/http_loadpoint_handler.go — per-loadpoint endpoints
  • server/socket.go — WebSocket pub/sub
  • assets/js/app.ts — Vue app entry
  • assets/js/store.ts — reactive state store
  • assets/js/api.ts — Axios clients
  • assets/js/router.ts — route definitions