### MQTT Host URL Examples

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

Provides examples of valid MQTT host URLs, including different protocols like `mqtt`, `mqtts`, `tcp`, `tls`, `ws`, and `wss`. It also highlights the importance of using the correct IP address when Z-Wave JS UI is in a Docker container.

```text
tls://localhost
mqtt://your_broker_ip:1883
ws://your_broker_ip:9001
```

--------------------------------

### Z-Wave JS Driver Options Override Example

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

Shows how to override options passed to the Z-Wave JS Driver constructor using the `zwave.options` setting in the `settings.json` file. This allows for advanced configuration not exposed in the UI.

```json
{
  "zwave": {
    "options": {
      "someDriverOption": "value",
      "anotherOption": true
    }
  }
}
```

--------------------------------

### Bash: Installing OpenSSL for HTTPS

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

This command installs OpenSSL, a prerequisite for enabling HTTPS in Z-Wave JS UI. The specific command may vary slightly depending on your operating system's package manager.

```bash
# For Debian/Ubuntu:
sudo apt update && sudo apt install openssl

# For Fedora/CentOS:
sudo yum install openssl

# For macOS (using Homebrew):
brew install openssl
```

--------------------------------

### Build and Run Z-Wave JS UI from GitHub Source

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/other-methods.md

Clones the Z-Wave JS UI repository from GitHub, installs dependencies using NPM, builds the project, and starts the application. This method requires NodeJS and NPM to be installed.

```bash
git clone https://github.com/zwave-js/zwave-js-ui
cd zwave-js-ui
npm install
npm run build
npm start
```

--------------------------------

### Z-Wave Network Key Transformation Example

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

Illustrates the conversion of an OZW format Z-Wave network key (including '0x' prefixes and commas) into the required format for Z-Wave JS UI (32 hexadecimal characters).

```text
(OZW) 0x5C, 0x14, 0x89, 0x74, 0x67, 0xC4, 0x25, 0x98, 0x51, 0x8A, 0xF1, 0x55, 0xDE, 0x6C, 0xCE, 0xA8
becomes
5C14897467C42598518AF155DE6CCEA8
```

--------------------------------

### Run Z-Wave JS UI Backend Server for Development

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/development/intro.md

Starts the backend server for development, including inspect and auto-restart features. This command is used in the second terminal. By default, it proxies requests to a backend on localhost:8091.

```bash
npm run dev:server
```

--------------------------------

### ValueId Object with States Payload Example

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

An example of a ValueId object that includes a 'states' property, indicating that the value represents a selection from a predefined list. This is common for configuration parameters in Z-Wave devices.

```javascript
{
  id: "112-0-200",
  nodeId: 8,
  commandClass: 112,
  commandClassName: "Configuration",
  endpoint: 0,
  property: 200,
  propertyName: "Partner ID",
  propertyKey: undefined,
  type: "number",
  readable: true,
  writeable: true,
  description: undefined,
  label: "Partner ID",
  default: 0,
  genre: "config",
  min: 0,
  max: 1,
  step: undefined,
  unit: undefined,
  list: true,
  states: [
    {
      text: "Aeon Labs Standard Product",
      value: 0,
    },
    {
      text: "others",
      value: 1,
    },
  ],
  value: 0,
  lastUpdate: 1604044675644,
}
```

--------------------------------

### Start Mock Z-Wave Controller (Development Tools)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Starts a mock Z-Wave controller. This tool is useful for testing Z-Wave integration and backend logic without requiring physical Z-Wave hardware.

```bash
npm run fake-stick
```

--------------------------------

### Entire ValueId Object Payload Example

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

An example of a complete ValueId object that can be used as the payload in the Z-Wave JS UI gateway. This object contains comprehensive information about a Z-Wave value, including its ID, node details, command class, property, and metadata.

```javascript
{
  id: "38-0-targetValue",
  nodeId: 8,
  commandClass: 38,
  commandClassName: "Multilevel Switch",
  endpoint: 0,
  property: "targetValue",
  propertyName: "targetValue",
  propertyKey: undefined,
  type: "number",
  readable: true,
  writeable: true,
  description: undefined,
  label: "Target value",
  default: undefined,
  genre: "user",
  min: 0,
  max: 99,
  step: undefined,
  unit: undefined,
  list: false,
  value: undefined,
  lastUpdate: 1604044669393,
}
```

--------------------------------

### Run Z-Wave JS UI with Docker (Local Folder Persistence)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/quick-start.md

This command starts Z-Wave JS UI in a Docker container, using a local directory for data persistence. It maps necessary ports and the host's serial Z-Wave device. A 'store' directory will be created in the current working directory to hold persistent data. Replace the serial device placeholder.

```bash
mkdir store
docker run --rm -it -p 8091:8091 -p 3000:3000 --device=/dev/serial/by-id/insert_stick_reference_here:/dev/zwave \
-v $(pwd)/store:/usr/src/app/store zwavejs/zwave-js-ui:latest
```

--------------------------------

### Start Production Backend Server (API/Server)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Starts the production-ready backend server. This command assumes the TypeScript code has already been compiled to JavaScript.

```bash
npm run server
```

--------------------------------

### JSON Time-Value Payload Example

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

An example of the JSON payload format used for publishing time-value data in the Z-Wave JS UI gateway. This format includes a timestamp and the corresponding value.

```json
{
  "time": 1548683523859,
  "value": 10
}
```

--------------------------------

### API Call Example: Send Command (startLevelChange)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Example of sending a 'startLevelChange' command for the Multilevel Switch CC via MQTT.

```APIDOC
## API Call Example: Send Command (startLevelChange)

### Description
This example shows how to send the `startLevelChange` command, part of the Multilevel Switch CC, using MQTT.

### Method
PUBLISH

### Topic
`zwavejs/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/sendCommand/set`

### Payload
```json
{
	"args": [
		{
			"nodeId": 23,
			"commandClass": 38,
			"endpoint": 0
		},
		"startLevelChange",
		[{ "duration": "1m"}] // these are the args of the command
  ]
}
```
```

--------------------------------

### Install Z-Wave JS UI via Snap Package

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/other-methods.md

Installs the Z-Wave JS UI application using the Snap package manager. After installation, connect the package to use raw USB and hardware observation capabilities.

```bash
sudo snap install zwave-js-ui
sudo snap connect zwave-js-ui:raw-usb
sudo snap connect zwave-js-ui:hardware-observe
```

--------------------------------

### Run Z-Wave JS UI as a Docker Service

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/quick-start.md

This approach deploys Z-Wave JS UI as a Docker service using Docker Compose. First, download the `docker-compose.yml` file, then execute the `docker-compose up -d` command to start the service in detached mode. This method simplifies management and configuration.

```bash
wget https://raw.githubusercontent.com/zwave-js/zwave-js-ui/master/docker/docker-compose.yml
docker-compose up -d
```

--------------------------------

### Run Z-Wave JS UI Frontend Development Server

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/development/intro.md

Starts the webpack-dev server for frontend development with hot reloading enabled. This command is used in the first terminal. Access the development environment at http://localhost:8092.

```bash
npm run dev
```

--------------------------------

### Z-Wave Security Key Format Example

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

Demonstrates the expected format for Z-Wave network security keys (S0/S2). The key should be a 32-character hexadecimal string, without prefixes like '0x' or spaces, derived from the OZW key format.

```text
5C14897467C42598518AF155DE6CCEA8
```

--------------------------------

### Start Production Server from Compiled Code (Full Stack)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Starts the production server using the already compiled JavaScript code. This is typically used after running `npm run build:server`.

```bash
npm run start
```

--------------------------------

### Named Topics MQTT Topic Structure

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

Defines the automatically configured MQTT topic structure when using 'Named Topics' for the Z-Wave JS UI gateway. This structure includes the MQTT prefix, optional node location, node name, command class name, optional endpoint, property name, and property key.

```string
<mqtt_prefix>/<?node_location>/<node_name>/<class_name>/<?endpoint>/<propertyName>/<propertyKey>
```

--------------------------------

### Install Local Plugin from Git Clone (Bash)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/plugins.md

Steps to clone a plugin repository locally, install its dependencies, and prepare it for use with Z-Wave JS UI. This is useful for plugins not available on npm or for development.

```bash
git clone https://github.com/kvaster/zwavejs-prom.git
cd zwavejs-prom
npm install
```

--------------------------------

### Docker Multi-stage Build Dockerfile Example (Deployment)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

A conceptual Dockerfile snippet illustrating a multi-stage build. This allows for smaller final images by separating build dependencies from runtime.

```dockerfile
# Dockerfile (simplified example)

# Build stage
FROM node:18 as builder
WORKDIR /app
COPY package*.json ./ 
RUN npm install
COPY . .
RUN npm run build

# Production stage
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/api/server.js ./server.js # Example compiled server file
EXPOSE 8092
CMD [ "node", "server.js" ]
```

--------------------------------

### Get Provisioning Entries in Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Retrieves a list of all Smart Start provisioning entries. This asynchronous function returns an array of SmartStartProvisioningEntry objects. The MQTT command is invoked with an empty arguments payload.

```typescript
async getProvisioningEntries(): Promise<SmartStartProvisioningEntry[]>;
```

```json
{
	"args": []
}
```

--------------------------------

### JavaScript: Example of parsing function for MQTT send

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

This snippet demonstrates a JavaScript function that can be used to parse values before sending them via MQTT. It takes the value, valueId, node, and logger as arguments and must be synchronous. This is useful for transforming data before it's published.

```javascript
function(value, valueId, node, logger) {
  // Custom parsing logic here
  // Example: Convert value to a specific format
  return newValue;
}
```

--------------------------------

### Provision Smart Start Node

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Provisions a Smart Start node. This can be done via a direct API call or through MQTT.

```APIDOC
## POST /api/provisionSmartStartNode

### Description
Provisions a Smart Start node with the provided entry details.

### Method
POST

### Endpoint
`/api/provisionSmartStartNode`

### Parameters
#### Request Body
- **entry** (PlannedProvisioningEntry | string) - Required - The entry details for the node to be provisioned.

### Request Example
```json
{
	"args": [
		"entry_details"
	]
}
```

### Response
#### Success Response (200)
- **PlannedProvisioningEntry** - Details of the provisioned node.

#### Response Example
```json
{
  "entry": "provisioned_entry_details"
}
```

## MQTT Usage for provisionSmartStartNode

### Topic
`zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/provisionSmartStartNode/set`

### Payload
```json
{
	"args": [
		"entry"
	]
}
```
```

--------------------------------

### Docker Run Healthcheck Command for Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/docker.md

This command demonstrates how to add a healthcheck to a Z-Wave JS UI container when using the `docker run` command. It specifies the health command and the start period. The health check command uses wget to query the service's health endpoint.

```bash
docker run <other options here> --health-cmd="wget --no-verbose --spider --no-check-certificate --header "Accept: text/plain" https://localhost:8091/health || exit 1" --health-start-period=30s
```

--------------------------------

### ValueId Topics MQTT Topic Structure

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

Defines the automatically configured MQTT topic structure when using 'ValueId Topics' for the Z-Wave JS UI gateway. This structure includes the MQTT prefix, optional node location, node ID, command class, endpoint, property, and property key.

```string
<mqtt_prefix>/<?node_location>/<nodeId>/<commandClass>/<endpoint>/<property>/<propertyKey>
```

--------------------------------

### RESTful API Endpoint Example (Backend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Illustrates a typical RESTful API endpoint definition within the Express application. This example shows a GET request handler.

```typescript
// Example in api/app.ts or a separate router file
app.get('/api/status', (req, res) => {
  res.json({ status: 'running' });
});
```

--------------------------------

### API Call Example: Execute Scene

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Example of how to execute a scene with a specific ID using MQTT.

```APIDOC
## API Call Example: Execute Scene

### Description
This example demonstrates how to execute a scene identified by its ID via MQTT.

### Method
PUBLISH

### Topic
`zwave/_CLIENTS/ZWAVE_GATEWAY-office/api/_activateScene/set`

### Payload
```json
{
	"args": [
		1 // id of scene
	]
}
```
```

--------------------------------

### Install and Run Z-Wave JS UI via NPM

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/other-methods.md

Installs Z-Wave JS UI globally using NPM and provides commands to run it. It's crucial to configure a custom storage path to prevent data loss during updates.

```bash
npm install -g zwave-js-ui
zwave-js-ui
STORE_DIR=~/.zwave-js-ui \
zwave-js-ui
```

--------------------------------

### JavaScript: Example of parsing function for MQTT receive

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

This snippet shows a JavaScript function for parsing values received via MQTT. Similar to the send function, it accepts value, valueId, node, and logger, and must be synchronous. This allows for custom handling of incoming MQTT messages.

```javascript
function(value, valueId, node, logger) {
  // Custom parsing logic here
  // Example: Process incoming data before Z-Wave JS UI handles it
  return parsedValue;
}
```

--------------------------------

### Z-Wave JS UI Docker Compose Service Configuration

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/docker.md

This docker-compose.yml file defines a service for running Z-Wave JS UI. It configures the image, restart policy, serial device mapping, volumes for data persistence, and port mappings for the web interface and WebSocket server. It also includes an option for setting the timezone.

```yaml
version: '3.7'
services:
    zwave-js-ui:
        container_name: zwave-js-ui
        image: zwavejs/zwave-js-ui:latest
        restart: always
        tty: true
        stop_signal: SIGINT
        environment:
            - SESSION_SECRET=mysupersecretkey
            # Uncomment if you want log times and dates to match your timezone instead of UTC
            # Available at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
            #- TZ=America/New_York
        networks:
            - zwave
        devices:
            # Do not use /dev/ttyUSBX serial devices, as those mappings can change over time.
            # Instead, use the /dev/serial/by-id/X serial device for your Z-Wave stick.
            - '/dev/serial/by-id/insert_stick_reference_here:/dev/zwave'
        volumes:
            - zwave-config:/usr/src/app/store
        # Or by using local folder
        # - ./store:/usr/src/app/store
        ports:
            - '8091:8091' # port for web interface
            - '3000:3000' # port for Z-Wave JS websocket server
networks:
    zwave:
volumes:
    zwave-config:
        name: zwave-config
```

--------------------------------

### Provision Smart Start Node via MQTT

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

This snippet shows how to provision a Smart Start node using MQTT. It requires a JSON payload containing the entry for the node to be provisioned. The topic specifies the API endpoint for this action.

```json
{
	"args": [
		entry
	]
}
```

--------------------------------

### Package Z-Wave JS UI Application

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/development/intro.md

Builds a package of the Z-Wave JS UI application. After running this command, follow the on-screen prompts to complete the packaging process.

```bash
npm run pkg
```

--------------------------------

### Docker Compose Healthcheck Configuration for Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/docker.md

This configuration integrates a healthcheck directly into a Docker Compose service definition for Z-Wave JS UI. It specifies the test command, interval, timeout, start period, and retries for the healthcheck. The test command uses wget to verify the service's health.

```yaml
version: '3.7'
services:
    zwave-js-ui:
    # ..... other settings .....
      healthcheck:
          test: 'wget --no-verbose --spider --no-check-certificate --header "Accept: text/plain" https://localhost:8091/health || exit 1'
          interval: 1m
          timeout: 10s
          start_period: 30s
          retries: 3
```

--------------------------------

### Install Plugin via npm

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/plugins.md

This command installs a custom plugin, assuming it's published as an npm package. Ensure the plugin is compatible with Z-Wave JS UI.

```bash
npm i my-awesome-plugin
```

--------------------------------

### Mocha Test Example (Backend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

A simple example of a backend test written using Mocha and Chai. This demonstrates how to test API endpoints or utility functions.

```javascript
// Example in api/tests/server.test.ts
import chai from 'chai';
import request from 'supertest';
import app from '../../api/app'; // Assuming app is exported

const expect = chai.expect;

describe('API Endpoints', () => {
  it('should return status running', async () => {
    const res = await request(app)
      .get('/api/status')
      .expect(200);
    expect(res.body.status).to.equal('running');
  });
});
```

--------------------------------

### Install libseccomp2 on Raspberry Pi (Buster)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/troubleshooting/app_crash.md

This sequence of commands adds the necessary Debian backports repository and installs the `libseccomp2` package. This is a workaround for startup crashes on older Raspbian Buster versions when running Z-Wave JS UI 8.2.0+.

```bash
sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com:443 --recv-keys 04EE7237B7D453EC 648ACFD622F3D138
echo "deb http://httpredir.debian.org/debian buster-backports main contrib non-free" | sudo tee -a "/etc/apt/sources.list.d/debian-backports.list"
sudo apt update
sudo apt install libseccomp2 -t buster-backports
```

--------------------------------

### Z-Wave Node Inclusion Example (Z-Wave Integration)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Conceptual example of initiating a Z-Wave node inclusion process using the Z-Wave JS library. This is a core function for adding new devices.

```typescript
// Example within ZwaveClient.ts
async startInclusion() {
  await this.driver. inclusión.start();
  console.log('Inclusion started...');
}
```

--------------------------------

### Get Provisioning Entry by DSK in Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Retrieves a single Smart Start provisioning entry based on its DSK. Returns the entry if found, otherwise undefined. The MQTT command requires the DSK string in its payload.

```typescript
getProvisioningEntry(dsk: string): SmartStartProvisioningEntry | undefined;
```

```json
{
	"args": [
		dsk
	]
}
```

--------------------------------

### Start Inclusion

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Initiates the Z-Wave inclusion process, allowing new devices to be added to the network. Various strategies and options can be specified.

```APIDOC
## POST /api/startInclusion

### Description
Starts the Z-Wave inclusion process to add new devices to the network.

### Method
POST

### Endpoint
`/api/startInclusion`

### Parameters
#### Request Body
- **args** (array) - Required - An array containing the `strategy` and optional `options`.
  - **strategy** (string) - Optional - The inclusion strategy to use (e.g., `"Default"`, `"Security_S2"`). Defaults to `InclusionStrategy.Default`.
  - **options** (object) - Optional - Additional options for the inclusion process.
    - **forceSecurity** (boolean) - Optional - Force security to be used during inclusion.
    - **provisioning** (object) - Optional - Provisioning entry details.
    - **qrString** (string) - Optional - QR code string for S2 inclusion.
    - **name** (string) - Optional - A name for the included device.
    - **dsk** (string) - Optional - Device specific key for inclusion.
    - **location** (string) - Optional - The location of the included device.

### Request Example
```json
{
	"args": [
		"Security_S2",
		{
			"forceSecurity": true,
			"name": "My Sensor"
		}
	]
}
```

### Response
#### Success Response (200)
- **result** (boolean) - True if the inclusion process was started successfully, false otherwise.

#### Response Example
```json
{
	"result": true
}
```
```

--------------------------------

### Minimal Custom Plugin Example (JavaScript)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/plugins.md

A basic structure for a custom Z-Wave JS UI plugin. It demonstrates how to access Z-Wave, MQTT, Express, and logger instances from the context, and includes a placeholder for a destroy function for cleanup.

```javascript
function MyPlugin (ctx) {
  this.zwave = ctx.zwave
  this.mqtt = ctx.mqtt
  this.logger = ctx.logger
  this.express = ctx.app

  // this.express.get('/my-route', function(req, res) {...})
  // this.mqtt.publish(...)
  // this.zwave.on('valueChanged', onValueChanged)
  // ... add all the stuff you need here
}

MyPlugin.prototype.destroy = async function () {
  // clean up the state
}

module.export = MyPlugin
```

--------------------------------

### Configured Manually MQTT Topic Structure

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/usage/setup.md

Defines the manually configured MQTT topic structure when using 'Configured Manually' for the Z-Wave JS UI gateway. This structure includes the MQTT prefix, optional node location, node name, and a user-defined value topic.

```string
<mqtt_prefix>/<?node_location>/<node_name>/<value_topic>
```

--------------------------------

### Start Development Server with HTTPS (UI)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Starts the development server for the Vue.js frontend with HTTPS enabled. This is useful for testing features that require secure connections.

```bash
npm run dev-https
```

--------------------------------

### Socket.IO Client Connection (Frontend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Example of establishing a Socket.IO connection from the frontend to the backend server. This enables receiving real-time updates.

```javascript
// In main.js or a relevant component
import { io } from 'socket.io-client';

const socket = io('http://localhost:8092'); // Use your backend URL

socket.on('connect', () => {
  console.log('Connected to backend via Socket.IO');
});

socket.on('device_updated', (data) => {
  console.log('Device updated:', data);
  // Update Pinia store or component state
});
```

--------------------------------

### Start Inclusion - TypeScript and MQTT

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Initiates the Z-Wave inclusion process. This function allows specifying an `InclusionStrategy` and various options, such as security settings, provisioning data, or device DSK. The MQTT command supports these parameters in its payload.

```typescript
async startInclusion(
	strategy: InclusionStrategy = InclusionStrategy.Default,
	options?: {
		forceSecurity?: boolean
		provisioning?: PlannedProvisioningEntry
		qrString?: string
		name?: string
		dsk?: string
		location?: string
	},
): Promise<boolean>;
```

```json
Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/startInclusion/set

Payload:
{
	"args": [
		strategy,
		options
	]
}
```

--------------------------------

### Example of Value ID Translation in Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/migrating.md

This example demonstrates how value IDs from `devices.js` are translated from the old Zwave2Mqtt format to the new Z-Wave JS UI format. This is crucial for understanding the impact on Home Assistant and MQTT configurations.

```diff
See https://github.com/zwave-js/zwave-js-ui/pull/20/files#diff-4a25087ac983e835241cfb02c43c408df47b81f77546ef07c4dcfe9acf019eeeR4 for translation examples.
```

--------------------------------

### Pinia Store Definition (Frontend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

A basic example of defining a Pinia store in the frontend application. Stores manage reactive application state.

```javascript
// src/stores/settings.js
import { defineStore } from 'pinia';

export const useSettingsStore = defineStore('settings', {
  state: () => ({
    mqttEnabled: false,
    mqttBroker: ''
  }),
  actions: {
    setMqttEnabled(enabled) {
      this.mqttEnabled = enabled;
    }
  }
});
```

--------------------------------

### Configure Z-Wave JS UI Service with PM2

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/other-methods.md

Sets up Z-Wave JS UI to run as a service using PM2. This involves installing PM2, creating an ecosystem configuration file, and starting/saving the service.

```javascript
module.exports = {
  apps : [
      {
        out_file: "/dev/null", // disable logs, use log to file when needed
        error_file: "/dev/null", // disable logs, use log to file when needed
        cwd: "~/",
        script: "zwave-js-ui",
        env: {
          STORE_DIR: "~/.zwave-js-ui",
        },
      },
  ]
}

// To run:
pm2 start ecosystem.config.js
pm2 save
pm2 startup
```

--------------------------------

### Home Assistant MQTT Discovery Payload (Z-Wave Integration)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Example of a JSON payload sent to Home Assistant's MQTT discovery topic to announce a new sensor entity. This enables automatic device integration in Home Assistant.

```json
{
  "name": "Living Room Light",
  "state_topic": "zwave/12345678/5/Basic/nodeStatus",
  "payload_on": "on",
  "payload_off": "off",
  "device_class": "light",
  "unique_id": "zwave-12345678-5-Basic"
}
```

--------------------------------

### Install Config Updates in Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Checks for and installs available configuration updates. This asynchronous function returns a boolean indicating success. The MQTT command requires an empty 'args' array for execution.

```typescript
async installConfigUpdate(): Promise<boolean>;

```

```json
{
	"args": []
}
```

--------------------------------

### Configuration Management API

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

API endpoints for checking and installing configuration updates.

```APIDOC
## GET /api/checkForConfigUpdates

### Description
Checks for available configuration updates for Z-Wave devices.

### Method
GET

### Endpoint
`/api/checkForConfigUpdates/set`

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
	"args": []
}
```

### Response
#### Success Response (200)
- **result** (string | undefined) - A string indicating the update status or undefined if no updates are available.

#### Response Example
```json
{
	"result": "Updates available: DeviceDatabase V2.1"
}
```
```

```APIDOC
## POST /api/installConfigUpdate

### Description
Checks for and installs available configuration updates.

### Method
POST

### Endpoint
`/api/installConfigUpdate/set`

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
	"args": []
}
```

### Response
#### Success Response (200)
- **result** (boolean) - True if updates were installed successfully, false otherwise.

#### Response Example
```json
{
	"result": true
}
```
```

--------------------------------

### Start Exclusion - TypeScript and MQTT

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Begins the Z-Wave exclusion process. This function accepts `ExclusionOptions`, which can include disabling provisioning entries. The MQTT payload requires the `options` object for execution.

```typescript
async startExclusion(
	options: ExclusionOptions = {
		strategy: ExclusionStrategy.DisableProvisioningEntry,
	},
): Promise<boolean>;
```

```json
Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/startExclusion/set

Payload:
{
	"args": [
		options
	]
}
```

--------------------------------

### Serve Documentation with Docsify (Development Tools)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Serves the project's documentation using Docsify. This command allows developers to preview the documentation locally.

```bash
npm run docs
```

--------------------------------

### Run Z-Wave JS UI with Docker (Volume Persistence)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/quick-start.md

This command launches Z-Wave JS UI using Docker, mounting a named volume for data persistence. It maps ports 8091 and 3000, and maps the host's serial Z-Wave device to the container. Ensure you replace the placeholder for the serial device.

```bash
docker run --rm -it -p 8091:8091 -p 3000:3000 --device=/dev/serial/by-id/insert_stick_reference_here:/dev/zwave \
--mount source=zwave-js-ui,target=/usr/src/app/store zwavejs/zwave-js-ui:latest
```

--------------------------------

### Socket.IO Real-time Event Example (Backend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Demonstrates how to emit a Socket.IO event from the backend to notify connected clients. This is used for real-time updates like device status changes.

```typescript
// Example within a handler or SocketManager
import { Server } from 'socket.io';

const io = new Server(httpServer);

io.emit('device_updated', { id: 1, status: 'ready' });
```

--------------------------------

### Creating Binary Packages with pkg (Build)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Uses the `@yao-pkg/pkg` tool to package the Node.js application into a single executable file for different operating systems.

```bash
# This is typically run via npm run pkg
pkg .
```

--------------------------------

### Z-Wave Device State Update Handling (Z-Wave Integration)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Example of how the Z-Wave JS driver might report device status updates. This event handler is crucial for reflecting device states in the UI and MQTT.

```typescript
// Example within ZwaveClient.ts
this.driver.on('node updated', (node) => {
  console.log(`Node ${node.id} updated: ${node.status}`);
  // Update state and emit via Socket.IO/MQTT
});
```

--------------------------------

### Get Priority SUC Return Route MQTT Payload (JSON)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Example MQTT payload for the `getPrioritySUCReturnRoute` API call. It includes an array with the node ID for the Z-Wave JS UI.

```json
{
	"args": [
		nodeId
	]
}
```

--------------------------------

### Vue Application Entry Point (Frontend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

The main JavaScript file that initializes the Vue application. It sets up the Vue instance, mounts the root component, and configures plugins.

```javascript
// src/main.js
// ... Vue instance creation ...
```

--------------------------------

### Get Priority Return Route MQTT Payload (JSON)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Example MQTT payload for the `getPriorityReturnRoute` API call. It includes an array of arguments, node IDs, for the Z-Wave JS UI.

```json
{
	"args": [
		nodeId,
		destinationId
	]
}
```

--------------------------------

### Bash Healthcheck Command for Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/docker.md

This command checks the health status of the Z-Wave JS UI service. It uses wget to send a request to the /health endpoint and exits with an error code if the check fails. It supports HTTPS by default but can be modified for HTTP.

```bash
wget --no-verbose --spider --no-check-certificate --header "Accept: text/plain" https://localhost:8091/health || exit 1
```

--------------------------------

### Settings JSON File Structure (Configuration)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Illustrative structure of the `store/settings.json` file, which holds application configuration like MQTT settings and authentication status.

```json
{
  "mqtt": {
    "enabled": true,
    "host": "mqtt.local",
    "port": 1883
  },
  "security": {
    "enableAuthentication": false
  }
}
```

--------------------------------

### Bundle Application using esbuild (Full Stack)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Bundles the application using esbuild, a fast JavaScript bundler. This command is used for creating optimized production builds.

```bash
npm run bundle
```

--------------------------------

### Download and Run Packaged Z-Wave JS UI Version

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/getting-started/other-methods.md

Downloads the latest packaged version of Z-Wave JS UI directly from GitHub releases using curl and wget, then unzips and runs the executable. This method does not require NodeJS/NPM.

```bash
cd ~
mkdir zwave-js-ui
cd zwave-js-ui
# download latest version
curl -s https://api.github.com/repos/zwave-js/zwave-js-ui/releases/latest  \
| grep "browser_download_url.*zip" \
| cut -d : -f 2,3 \
| tr -d "" \
| wget -i -
unzip zwave-js-ui-v*.zip
./zwave-js-ui
```

--------------------------------

### Run All Tests (Testing and Quality)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Executes all configured tests for both the backend (server) and frontend (UI) components of the application. This ensures comprehensive code quality checks.

```bash
npm run test
```

--------------------------------

### Build Full Stack Application (Full Stack)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Builds both the frontend (Vue.js) and backend (TypeScript) parts of the application. This command is used to prepare the application for production deployment.

```bash
npm run build
```

--------------------------------

### Vue Test Example (Frontend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

An example of a frontend component test using Vue Test Utils and potentially Jest or Mocha. This tests a Vue component's behavior.

```javascript
// Example in src/components/MyComponent.test.js
import { mount } from '@vue/test-utils';
import MyComponent from '@/components/MyComponent.vue';

describe('MyComponent', () => {
  it('renders correctly', () => {
    const wrapper = mount(MyComponent);
    expect(wrapper.find('h1').text()).toBe('Welcome');
  });
});
```

--------------------------------

### Begin Rebuilding Z-Wave Routes

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Starts the process of rebuilding routes within the Z-Wave network. This function accepts optional configuration options and returns a boolean indicating if the process was started successfully. It can be controlled via MQTT.

```typescript
beginRebuildingRoutes(options?: RebuildRoutesOptions): boolean;
```

```json
{
	"args": [
		options
	]
}
```

--------------------------------

### Unprovision Smart Start Node in Z-Wave JS UI

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Removes a Smart Start provisioning entry for a specific node, identified by its DSK or Node ID. This function does not return a value. The MQTT payload includes the DSK or Node ID.

```typescript
unprovisionSmartStartNode(dskOrNodeId: string | number): void;
```

```json
{
	"args": [
		dskOrNodeId
	]
}
```

--------------------------------

### Vite Frontend Bundling (Build)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Vite is used to bundle the Vue.js frontend application. It provides a fast development server and optimized production builds.

```bash
# This is typically run via npm run build or npm run build:ui
vite build
```

--------------------------------

### Build Docker Image (Development Tools)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Builds the Docker image for the Zwave-JS UI application. This is used for containerized deployment and consistent environments.

```bash
npm run docker:build
```

--------------------------------

### Get Available Firmware Updates

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Retrieves a list of available firmware updates for a specified Z-Wave node.

```APIDOC
## POST /api/getAvailableFirmwareUpdates

### Description
Retrieves a list of available firmware updates for a specified Z-Wave node.

### Method
POST

### Endpoint
`/api/getAvailableFirmwareUpdates`

### Parameters
#### Request Body
- **args** (array) - Required - An array containing the `nodeId` and optional `options`.
  - **nodeId** (number) - Required - The ID of the node to check for firmware updates.
  - **options** (object) - Optional - Additional options for fetching firmware updates.

### Request Example
```json
{
	"args": [
		3
	]
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of available firmware update details.
  - **version** (string) - The version of the firmware update.
  - **changelog** (string) - The changelog for the firmware update.
  - **channel** (string) - The release channel (e.g., "stable", "beta").
  - **files** (array) - Information about the firmware update files.
  - **downgrade** (boolean) - Indicates if a downgrade is possible.
  - **normalizedVersion** (string) - The normalized version string.
  - **device** (object) - Information about the device.

#### Response Example
```json
{
	"result": [
		{
			"version": "1.2.0",
			"changelog": "Fixed a bug.",
			"channel": "stable",
			"files": [],
			"downgrade": false,
			"normalizedVersion": "1.2.0",
			"device": {
				"manufacturerId": 123,
				"productType": 456,
				"productId": 789,
				"firmwareVersion": "1.1.0"
			}
		}
	]
}
```
```

--------------------------------

### NVM and Configuration Backup (Backend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Handles the backup and restoration of Z-Wave network NVM (Non-Volatile Memory) and configuration data. Stores backups in the `store/backups/` directory.

```typescript
// api/lib/BackupManager.ts
// ... backup and restore functions ...
```

--------------------------------

### Configure Z-Wave JS UI Backend Connection (Environment Variables)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/development/intro.md

Sets environment variables to redirect the development frontend to a different backend server. These variables allow customization of the server host, port, SSL usage, and full URLs for API and WebSocket connections.

```bash
export SERVER_HOST='your_backend_host'
export SERVER_PORT='your_backend_port'
export SERVER_SSL='true'
export SERVER_URL='https://your_backend.com:port/'
export SERVER_WS_URL='wss://your_backend.com:port/'
export INGRESS_TOKEN='your_ingress_token'
```

--------------------------------

### Start Exclusion

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Initiates the Z-Wave exclusion process, allowing devices to be removed from the network. Different exclusion strategies can be applied.

```APIDOC
## POST /api/startExclusion

### Description
Starts the Z-Wave exclusion process to remove devices from the network.

### Method
POST

### Endpoint
`/api/startExclusion`

### Parameters
#### Request Body
- **args** (array) - Required - An array containing the optional `options`.
  - **options** (object) - Optional - Options for the exclusion process.
    - **strategy** (string) - Optional - The exclusion strategy to use (e.g., `"DisableProvisioningEntry"`). Defaults to `ExclusionStrategy.DisableProvisioningEntry`.

### Request Example
```json
{
	"args": [
		{
			"strategy": "DisableProvisioningEntry"
		}
	]
}
```

### Response
#### Success Response (200)
- **result** (boolean) - True if the exclusion process was started successfully, false otherwise.

#### Response Example
```json
{
	"result": true
}
```
```

--------------------------------

### POST /api/getProvisioningEntry

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/mqtt.md

Retrieves a specific SmartStart provisioning entry by its DSK. This is a synchronous operation.

```APIDOC
## POST /api/getProvisioningEntry

### Description
Retrieves a specific SmartStart provisioning entry by its DSK. This is a synchronous operation.

### Method
POST

### Endpoint
`/api/getProvisioningEntry`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **args** (array) - Required - Contains one element:
    * **dsk** (string) - Required - The DSK of the provisioning entry to retrieve.

### Request Example
```json
{
	"args": [
		"123-456-789"
	]
}
```

### Response
#### Success Response (200)
* **SmartStartProvisioningEntry | undefined** - The provisioning entry if found, otherwise `undefined`.

#### Response Example
```json
{
  "DSK": "123-456-789",
  "newNodeId": 5,
  "active": true,
  "owner": "John Doe",
  "label": "Living Room Light"
}
```
```

--------------------------------

### GET /health/zwave

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/healthcheck.md

Checks the connection status of the Z-Wave client. Returns 200 if the Z-Wave client is connected, and 500 otherwise.

```APIDOC
## GET /health/zwave

### Description
Checks the connection status of the Z-Wave client. Returns 200 if the Z-Wave client is connected, and 500 otherwise.

### Method
GET

### Endpoint
/health/zwave

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl localhost:8091/health/zwave -H "Accept: text/plain"
```

### Response
#### Success Response (200)
Indicates that the Z-Wave client is connected.

#### Error Response (500)
Indicates that the Z-Wave client is not connected.

#### Response Example
(No specific response body is defined, the status code is the primary indicator)

```

--------------------------------

### GET /health/mqtt

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/docs/guide/healthcheck.md

Checks the connection status of the MQTT client. Returns 200 if the MQTT client is connected, and 500 otherwise.

```APIDOC
## GET /health/mqtt

### Description
Checks the connection status of the MQTT client. Returns 200 if the MQTT client is connected, and 500 otherwise.

### Method
GET

### Endpoint
/health/mqtt

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl localhost:8091/health/mqtt -H "Accept: text/plain"
```

### Response
#### Success Response (200)
Indicates that the MQTT client is connected.

#### Error Response (500)
Indicates that the MQTT client is not connected.

#### Response Example
(No specific response body is defined, the status code is the primary indicator)

```

--------------------------------

### Build Vue.js Frontend Application (UI)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Compiles and builds the Vue.js frontend application for production. This command generates static assets optimized for deployment.

```bash
npm run build:ui
```

--------------------------------

### JWT Authentication Check (Backend)

Source: https://github.com/zwave-js/zwave-js-ui/blob/master/CLAUDE.md

Shows a middleware example for checking JWT (JSON Web Token) authentication on incoming requests. This is used to secure sensitive API endpoints.

```typescript
// Example middleware function
function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];

  if (token == null) return res.sendStatus(401);

  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {
    if (err) return res.sendStatus(403);
    req.user = user;
    next();
  });
}

app.get('/api/protected', authenticateToken, (req, res) => {
  res.send('This is a protected route!');
});
```