homeui

Wiren Board web interface.

MQTT naming conventions

See into conventions to understand how to organize devices and controls (what write to /meta/type for example).

NGINX configuration

The config is stored in /usr/share/wb-mqtt-homeui/nginx/default.conf (do not edit this file directly). Add your custom configuration to /etc/nginx/includes/default.wb.d/*.conf. Change listen settings in /etc/nginx/includes/default.wb.d/listen.conf.

Running local development

1. Navigate to the project directory: cd ./frontend
2. Install dependencies: npm install
3. Create .env file and set MQTT_BROKER_URI if your controller is running on different IP (default is 10.200.200.1)
4. Start the development server: npm run dev

Before committing

Run these checks in ./frontend before opening a PR:

cd frontend
npm install
npx tsc --noemit  # TypeScript type check
npm run lint  # ESLint static analysis

Custom menu

One can put JSON-files with custom menu descriptions into the /etc/wb-homeui/custom-menu directory (persisted across firmware updates via wb-configs; the symlink into /mnt/data appears after the next reboot). Items defined in those files are added to the left navigation panel. /usr/share/wb-mqtt-homeui/custom-menu is still read too (package drop-ins / legacy files); /var/lib/wb-homeui/custom-menu holds files generated by service gates — do not edit by hand. Read order: /usr/share, then /var/lib, then /etc — gate-generated items always follow /usr/share drop-ins.

The structure of the JSON-file

[
  {
    "id": "string",
    // Not used if id is already defined
    "url": "string",
    // Not used if id is already defined
    "title": {
      "en": "string",
      "ru": "string"
    },
    // Optional. Without it (the default) url is an internal homeui route — relative
    // urls to pages inside homeui keep working as before. Set to true for a link
    // that leaves homeui: it renders as a plain full-page link; url must then be an
    // absolute path or an http(s) URL, otherwise the flag is ignored
    "isExternal": true,
    // With isExternal: open in a new tab (rel="noopener noreferrer" is applied)
    "openInNewTab": true,
    // Optional. Minimal role to SEE the item: "user" < "operator" < "admin";
    // absent = visible to all. Affects visibility only — the page or service the
    // url points at must check access rights itself
    "requiredRole": "admin",
    "children": [
      {
        "id": "string",
        "url": "string",
        "title": {
          "en": "string",
          "ru": "string"
        }
      }
    ]
  }
]

Developer documentation

• JSON Schema editor — homeui's own schema-driven form editor (React + MobX), successor to the legacy forked @wirenboard/json-editor.