Z-Wave JS Server

Exposes the unified credential management API from Z-Wave JS under the endpoint.access_control.* namespace. This is compatible with schema version 48+.

Workflow: Before using credential commands, applications should check if the endpoint supports the unified access control API using endpoint.access_control.is_supported. The response contains a supported: boolean field.

Supported Commands:

• endpoint.access_control.is_supported (Check support)
• endpoint.access_control.get_user_capabilities_cached / get_credential_capabilities_cached (Get capabilities)
• endpoint.access_control.get_user / get_user_cached / get_users / get_users_cached (Get users)
• endpoint.access_control.set_user / delete_user / delete_all_users (Manage users)
• endpoint.access_control.get_credential / get_credential_cached / get_credentials / get_credentials_cached / get_credentials_by_type / get_credentials_by_type_cached / get_all_credentials / get_all_credentials_cached (Get credentials)
• endpoint.access_control.assign_credential (Reassign credential)
• endpoint.access_control.set_credential / delete_credential (Manage credentials)
• endpoint.access_control.start_credential_learn / cancel_credential_learn (Credential learning)
• endpoint.access_control.get_admin_code / set_admin_code (Admin code management)

Mutating Command Results: Mutating commands return a result field with specific enum values:

• set_user, delete_user, delete_all_users $\rightarrow$ SetUserResult
• set_credential, delete_credential $\rightarrow$ SetCredentialResult
• assign_credential $\rightarrow$ AssignCredentialResult

Examples:

Set a credential:

{
  "messageId": "string",
  "command": "endpoint.access_control.set_credential",
  "nodeId": number,
  "endpoint": number,
  "userId": number,
  "credentialType": number,
  "credentialSlot": number,
  "data": "string" | { "type": "Buffer", "data": number[] }
}

Create or modify a user:

{
  "messageId": "string",
  "command": "endpoint.access_control.set_user",
  "nodeId": number,
  "endpoint": number,
  "userId": number,
  "options": {
    "active": boolean,
    "userType": number,
    "userName": "string",
    "credentialRule": number,
    "expiringTimeoutMinutes": number
  }
}

The Z-Wave JS Server API evolves through versioned schemas. Each schema version introduces new commands, state properties, or changes to existing data structures. When integrating with the server, you should be aware of the schema version being used to ensure compatibility with the available commands and the shape of the state dumps.

Key types of changes include:

• New Commands: Addition of namespaces like driver.*, controller.*, node.*, or endpoint.*.
• State Changes: New properties added to NodeState, ControllerState, or Endpoint state dumps.
• Event Changes: New controller or node events (e.g., statistics updated, interview started).
• Breaking Changes: Renaming of properties (e.g., version to protocolVersion) or changes in parameter types/return shapes.

Refer to the specific schema version documentation to map your client logic to the server's capabilities.

Because callbacks cannot be passed over a WebSocket connection, the Z-Wave JS Server automatically converts several controller methods that typically accept callback parameters into an event-driven model. Instead of providing a callback function in the command payload, the server emits specific events to the client to signal progress or required user interaction.

Key conversions include:

• Inclusion/Joining: For controller.begin_inclusion, controller.replace_failed_node, and controller.begin_joining_network, the server handles userCallbacks (like S2 security bootstrapping) and emits events such as grant security classes, validate dsk and enter pin, inclusion aborted, joining network show dsk, or joining network done.
• NVM Operations: controller.backup_nvm_raw reports progress via nvm backup progress events. controller.restore_nvm and controller.restore_nvm_raw use nvm convert progress and nvm restore progress events.
• Firmware Updates: controller.firmware_update_otw accepts a base64 encoded file and a filename.
• NVM Buffers: Commands like controller.external_nvm_read_buffer return NVM data as a base64 encoded string in the buffer field. For writes, the buffer input must be a base64 encoded string.

When a client connects to the server, the following lifecycle occurs:

1. Version Handshake: The server immediately sends a version message containing driverVersion, serverVersion, homeId, and schema version ranges (minSchemaVersion, maxSchemaVersion).
2. Driver Readiness: If the driver is not yet ready, the server closes the connection with error code 1013 (Try Again Later). Clients should implement a retry mechanism.
3. Initialization: The client should send an initialize command to specify its supported schemaVersion and optional additionalUserAgentComponents.
4. Listening: The client sends a start_listening command to receive the current state and subsequent events.

Data Formats

Version Message (Server -> Client):

{
  type: "version",
  driverVersion: string,
  serverVersion: string,
  homeId: number | undefined,
  minSchemaVersion: number,
  maxSchemaVersion: number
}

Initialize Command (Client -> Server):

{
  messageId: string,
  command: "initialize",
  schemaVersion: number,
  additionalUserAgentComponents?: Record<string, string>
}

Start Listening Command (Client -> Server):

{
  messageId: string,
  command: "start_listening"
}

State Result (Server -> Client):

{
  type: "result",
  messageId: string, // maps to the start_listening command
  success: true,
  result: {
    state: {
      driver: Partial<DriverState>;
      controller: Partial<ZWaveController>;
      nodes: Partial<ZWaveNode>[];
    }
  }
}

Z-Wave JS Server uses an API Schema Versioning system to maintain compatibility between different server and client versions.

When a client connects, the server sends a version message containing minSchemaVersion and maxSchemaVersion. The client should then use the set_api_schema command to tell the server which schema version it intends to use.

Key behaviors:

• Default Behavior: If the client does not send set_api_schema, the server defaults to the minimum supported schema (currently 0).
• Multi-client Support: The server can handle multiple clients simultaneously, even if they are using different schema versions.
• Breaking Changes: When breaking changes are introduced to the API, the schema version is bumped. New features will also bump the schema version.
• Out of Range: If a client requests a version outside the server's supported range, the server returns a schema_incompatible error.

// 1. Server sends version info upon connection
{
  "type": "version",
  "driverVersion": "6.5.0",
  "serverVersion": "1.0.0",
  "homeId": 3967882672,
  "minSchemaVersion": 0,
  "maxSchemaVersion": 1
}

// 2. Client sets the desired schema version
{
  "command": "set_api_schema",
  "messageId": 1,
  "schemaVersion": 1
}