home-assistant
/
zwave-js-ui
mirror of https://github.com/zwave-js/zwave-js-ui.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
zwave-js-ui/docs/guide/mqtt.md

38 KiB
Raw Permalink Blame History

Using MQTT

You have access to almost all of the Z-Wave JS APIs (and more) via MQTT.

Z-Wave Events

If the Send Z-Wave Events flag of Gateway settings is enabled all Z-Wave JS events are published to MQTT. There are Driver, Node and Controller events

Topic

<mqtt_prefix>/_EVENTS_/ZWAVE_GATEWAY-<mqtt_name>/<driver|node|controller>/<event_name>

Payload

{
  "data": [ ...eventArgs ] // an array containing all args in order
}

Z-Wave APIs

To call a Z-Wave API you just need to publish a JSON object like:

{
	"args": [2, 1]
}

Where args is an array with the args used to call the api, the topic is:

<mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/<api_name>/set

The result will be published on the same topic without /set

Api call examples

Execute Scene

Execute the scene with the id 1 via mqtt.

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-office/api/_activateScene/set

Payload:

{
	"args": [
		1 // id of scene
	]
}

Send Command

Example calling startLevelChange command:

Topic: zwavejs/_CLIENTS/ZWAVE_GATEWAY-<yourName>/api/sendCommand/set

Payload:

{ 
	"args": [
		{
			"nodeId": 23,
			"commandClass": 38,
			"endpoint": 0,
		},
		"startLevelChange",
		[{ duration: "1m"}] // this are the args of the command
  ]
}

APIs

This are the available APIs:

restart

async restart(): Promise<void>;

Restart client connection.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/restart/set

Payload:

{
	"args": []
}

getSchedules

async getSchedules(
	nodeId: number,
	opts: { mode?: ZUIScheduleEntryLockMode; fromCache: boolean } = {
		fromCache: true,
	},
): Promise<ZUISchedule>;

If the node supports Schedule Lock CC parses all available schedules and cache them.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getSchedules/set

Payload:

{
	"args": [
		nodeId,
		opts
	]
}

cancelGetSchedule

cancelGetSchedule(): void;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/cancelGetSchedule/set

Payload:

{
	"args": []
}

setSchedule

async setSchedule(
	nodeId: number,
	type: 'daily' | 'weekly' | 'yearly',
	schedule: ScheduleEntryLockSlotId &
		(
			| ScheduleEntryLockDailyRepeatingSchedule
			| ScheduleEntryLockWeekDaySchedule
			| ScheduleEntryLockYearDaySchedule
		),
): Promise<SupervisionResult>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setSchedule/set

Payload:

{
	"args": [
		nodeId,
		type,
		schedule
	]
}

setEnabledSchedule

async setEnabledSchedule(nodeId: number, enabled: boolean, userId: number): Promise<SupervisionResult>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setEnabledSchedule/set

Payload:

{
	"args": [
		nodeId,
		enabled,
		userId
	]
}

getAssociations

async getAssociations(
	nodeId: number,
	refresh = false,
): Promise<ZUIGroupAssociation[]>;

Get an array of current associations of a specific group.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getAssociations/set

Payload:

{
	"args": [
		nodeId,
		refresh
	]
}

addAssociations

async addAssociations(
	source: AssociationAddress,
	groupId: number,
	associations: AssociationAddress[],
): Promise<boolean>;

Add a node to the array of specified associations.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/addAssociations/set

Payload:

{
	"args": [
		source,
		groupId,
		associations
	]
}

removeAssociations

async removeAssociations(
	source: AssociationAddress,
	groupId: number,
	associations: AssociationAddress[],
): Promise<void>;

Remove a node from an association group.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/removeAssociations/set

Payload:

{
	"args": [
		source,
		groupId,
		associations
	]
}

removeAllAssociations

async removeAllAssociations(nodeId: number): Promise<void>;

Remove all associations.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/removeAllAssociations/set

Payload:

{
	"args": [
		nodeId
	]
}

syncNodeDateAndTime

syncNodeDateAndTime(nodeId: number, date = new Date()): Promise<boolean>;

Setting the date and time on a node could be hard, this helper method will set it using the date provided (default to now).

The following CCs will be used (when supported or necessary) in this process:

  • Time Parameters CC
  • Clock CC
  • Time CC
  • Schedule Entry Lock CC (for setting the timezone).
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/syncNodeDateAndTime/set

Payload:

{
	"args": [
		nodeId,
		date
	]
}

manuallyIdleNotificationValue

manuallyIdleNotificationValue(valueId: ZUIValueId): void;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/manuallyIdleNotificationValue/set

Payload:

{
	"args": [
		valueId
	]
}

removeNodeFromAllAssociations

async removeNodeFromAllAssociations(nodeId: number): Promise<void>;

Remove node from all associations.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/removeNodeFromAllAssociations/set

Payload:

{
	"args": [
		nodeId
	]
}

refreshNeighbors

async refreshNeighbors(): Promise<Record<number, number[]>>;

Refresh all nodes neighbors.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/refreshNeighbors/set

Payload:

{
	"args": []
}

getNodeNeighbors

async getNodeNeighbors(
	nodeId: number,
	preventThrow = false,
	emitNodeUpdate = true,
): Promise<readonly number[]>;

Get neighbors of a specific node.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getNodeNeighbors/set

Payload:

{
	"args": [
		nodeId,
		preventThrow,
		emitNodeUpdate
	]
}

discoverNodeNeighbors

async discoverNodeNeighbors(nodeId: number): Promise<boolean>;

Instructs a node to (re-)discover its neighbors.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/discoverNodeNeighbors/set

Payload:

{
	"args": [
		nodeId
	]
}

driverFunction

driverFunction(code: string): Promise<any>;

Execute a driver function. More info here.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/driverFunction/set

Payload:

{
	"args": [
		code
	]
}

setNodeName

async setNodeName(nodeid: number, name: string): Promise<boolean>;

Updates node name property and stores updated config in nodes.json.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setNodeName/set

Payload:

{
	"args": [
		nodeid,
		name
	]
}

setNodeLocation

async setNodeLocation(nodeid: number, loc: string): Promise<boolean>;

Updates node loc property and stores updated config in nodes.json.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setNodeLocation/set

Payload:

{
	"args": [
		nodeid,
		loc
	]
}

setNodeDefaultSetValueOptions

setNodeDefaultSetValueOptions(
	nodeId: number,
	props: Pick<ZUINode, 'defaultTransitionDuration' | 'defaultVolume'>,
): void;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setNodeDefaultSetValueOptions/set

Payload:

{
	"args": [
		nodeId,
		props
	]
}

_createScene

async _createScene(label: string): Promise<boolean>;

Creates a new scene with a specific label and stores it in scenes.json.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_createScene/set

Payload:

{
	"args": [
		label
	]
}

_removeScene

async _removeScene(sceneid: number): Promise<boolean>;

Delete a scene with a specific sceneid and updates scenes.json.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_removeScene/set

Payload:

{
	"args": [
		sceneid
	]
}

_setScenes

async _setScenes(scenes: ZUIScene[]): Promise<ZUIScene[]>;

Imports scenes Array in scenes.json.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_setScenes/set

Payload:

{
	"args": [
		scenes
	]
}

_getScenes

_getScenes(): ZUIScene[];

Get all scenes.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_getScenes/set

Payload:

{
	"args": []
}

_sceneGetValues

_sceneGetValues(sceneid: number): ZUIValueIdScene[];

Return all values of the scene with given sceneid.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_sceneGetValues/set

Payload:

{
	"args": [
		sceneid
	]
}

_addSceneValue

async _addSceneValue(
	sceneid: number,
	valueId: ZUIValueIdScene,
	value: any,
	timeout: number,
): Promise<any>;

Add a value to a scene.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_addSceneValue/set

Payload:

{
	"args": [
		sceneid,
		valueId,
		value,
		timeout
	]
}

_removeSceneValue

async _removeSceneValue(sceneid: number, valueId: ZUIValueIdScene): Promise<any>;

Remove a value from scene.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_removeSceneValue/set

Payload:

{
	"args": [
		sceneid,
		valueId
	]
}

_activateScene

_activateScene(sceneId: number): boolean;

Activate a scene with given scene id.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/_activateScene/set

Payload:

{
	"args": [
		sceneId
	]
}

getNodes

getNodes(): ZUINode[];

Get the nodes array.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getNodes/set

Payload:

{
	"args": []
}

getInfo

getInfo(): ZUIDriverInfo;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getInfo/set

Payload:

{
	"args": []
}

refreshValues

refreshValues(nodeId: number): Promise<void>;

Refresh all node values.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/refreshValues/set

Payload:

{
	"args": [
		nodeId
	]
}

pingNode

pingNode(nodeId: number): Promise<boolean>;

Ping a node.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/pingNode/set

Payload:

{
	"args": [
		nodeId
	]
}

refreshCCValues

refreshCCValues(nodeId: number, cc: CommandClasses): Promise<void>;

Refresh all node values of a specific CC.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/refreshCCValues/set

Payload:

{
	"args": [
		nodeId,
		cc
	]
}

checkForConfigUpdates

async checkForConfigUpdates(): Promise<string | undefined>;

Checks for configs updates.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/checkForConfigUpdates/set

Payload:

{
	"args": []
}

installConfigUpdate

async installConfigUpdate(): Promise<boolean>;

Checks for configs updates and installs them.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/installConfigUpdate/set

Payload:

{
	"args": []
}

shutdownZwaveAPI

async shutdownZwaveAPI(): Promise<boolean>;

If supported by the controller, this instructs it to shut down the Z-Wave API, so it can safely be removed from power. If this is successful (returns true), the driver instance will be destroyed and can no longer be used.

[!WARNING] The controller will have to be restarted manually (e.g. by unplugging and plugging it back in) before it can be used again!.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/shutdownZwaveAPI/set

Payload:

{
	"args": []
}

pollValue

pollValue(valueId: ZUIValueId): Promise<unknown>;

Request an update of this value.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/pollValue/set

Payload:

{
	"args": [
		valueId
	]
}

replaceFailedNode

async replaceFailedNode(
	nodeId: number,
	strategy: InclusionStrategy = InclusionStrategy.Security_S2,
	options?: {
		qrString?: string
		provisioning?: PlannedProvisioningEntry
	},
): Promise<boolean>;

Replace failed node.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/replaceFailedNode/set

Payload:

{
	"args": [
		nodeId,
		strategy,
		options
	]
}

getAvailableFirmwareUpdates

async getAvailableFirmwareUpdates(
	nodeId: number,
	options?: GetFirmwareUpdatesOptions,
): Promise<{ version: string; changelog: string; channel: "stable" | "beta"; files: FirmwareUpdateFileInfo[]; downgrade: boolean; normalizedVersion: string; device: { manufacturerId: number; productType: number; productId: number; firmwareVersion: string; rfRegion?: RFRegion; }; }[]>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getAvailableFirmwareUpdates/set

Payload:

{
	"args": [
		nodeId,
		options
	]
}

firmwareUpdateOTA

async firmwareUpdateOTA(nodeId: number, updateInfo: FirmwareUpdateInfo): Promise<FirmwareUpdateResult>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/firmwareUpdateOTA/set

Payload:

{
	"args": [
		nodeId,
		updateInfo
	]
}

setPowerlevel

async setPowerlevel(
	powerlevel: number,
	measured0dBm: number,
): Promise<boolean>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setPowerlevel/set

Payload:

{
	"args": [
		powerlevel,
		measured0dBm
	]
}

setRFRegion

async setRFRegion(region: RFRegion): Promise<boolean>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setRFRegion/set

Payload:

{
	"args": [
		region
	]
}

startInclusion

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

Start inclusion.

Mqtt usage

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

Payload:

{
	"args": [
		strategy,
		options
	]
}

startExclusion

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

Start exclusion.

Mqtt usage

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

Payload:

{
	"args": [
		options
	]
}

stopExclusion

stopExclusion(): Promise<boolean>;

Stop exclusion.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/stopExclusion/set

Payload:

{
	"args": []
}

stopInclusion

stopInclusion(): Promise<boolean>;

Stops inclusion.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/stopInclusion/set

Payload:

{
	"args": []
}

rebuildNodeRoutes

async rebuildNodeRoutes(nodeId: number): Promise<boolean>;

Rebuild node routes.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/rebuildNodeRoutes/set

Payload:

{
	"args": [
		nodeId
	]
}

getPriorityReturnRoute

getPriorityReturnRoute(nodeId: number, destinationId: number): Route;

Get priority return route from nodeId to destinationId.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getPriorityReturnRoute/set

Payload:

{
	"args": [
		nodeId,
		destinationId
	]
}

assignPriorityReturnRoute

async assignPriorityReturnRoute(
	nodeId: number,
	destinationNodeId: number,
	repeaters: number[],
	routeSpeed: ZWaveDataRate,
): Promise<boolean>;

Assigns a priority return route from nodeId to destinationId.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/assignPriorityReturnRoute/set

Payload:

{
	"args": [
		nodeId,
		destinationNodeId,
		repeaters,
		routeSpeed
	]
}

getPrioritySUCReturnRoute

getPrioritySUCReturnRoute(nodeId: number): Route;

Get priority return route from node to controller.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getPrioritySUCReturnRoute/set

Payload:

{
	"args": [
		nodeId
	]
}

assignPrioritySUCReturnRoute

async assignPrioritySUCReturnRoute(
	nodeId: number,
	repeaters: number[],
	routeSpeed: ZWaveDataRate,
): Promise<boolean>;

Assign a priority return route from node to controller.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/assignPrioritySUCReturnRoute/set

Payload:

{
	"args": [
		nodeId,
		repeaters,
		routeSpeed
	]
}

getCustomReturnRoute

getCustomReturnRoute(nodeId: number, destinationId: number): Route[];

Get custom return routes from nodeId to destinationId.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getCustomReturnRoute/set

Payload:

{
	"args": [
		nodeId,
		destinationId
	]
}

assignCustomReturnRoutes

async assignCustomReturnRoutes(
	nodeId: number,
	destinationNodeId: number,
	routes: Route[],
	priorityRoute?: Route,
): Promise<boolean>;

Assigns custom return routes from a node to a destination node.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/assignCustomReturnRoutes/set

Payload:

{
	"args": [
		nodeId,
		destinationNodeId,
		routes,
		priorityRoute
	]
}

getCustomSUCReturnRoute

getCustomSUCReturnRoute(nodeId: number): Route[];

Get custom return routes from node to controller.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getCustomSUCReturnRoute/set

Payload:

{
	"args": [
		nodeId
	]
}

assignCustomSUCReturnRoutes

async assignCustomSUCReturnRoutes(
	nodeId: number,
	routes: Route[],
	priorityRoute?: Route,
): Promise<boolean>;

Assigns up to 4 return routes to a node to the controller.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/assignCustomSUCReturnRoutes/set

Payload:

{
	"args": [
		nodeId,
		routes,
		priorityRoute
	]
}

getPriorityRoute

async getPriorityRoute(nodeId: number): Promise<{ routeKind: RouteKind.LWR | RouteKind.NLWR | RouteKind.Application; repeaters: number[]; routeSpeed: ZWaveDataRate; }>;

Returns the priority route for a given node ID.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getPriorityRoute/set

Payload:

{
	"args": [
		nodeId
	]
}

deleteReturnRoutes

async deleteReturnRoutes(nodeId: number): Promise<boolean>;

Delete ALL previously assigned return routes.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/deleteReturnRoutes/set

Payload:

{
	"args": [
		nodeId
	]
}

deleteSUCReturnRoutes

async deleteSUCReturnRoutes(nodeId: number): Promise<boolean>;

Delete ALL previously assigned return routes to the controller.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/deleteSUCReturnRoutes/set

Payload:

{
	"args": [
		nodeId
	]
}

assignReturnRoutes

async assignReturnRoutes(nodeId: number, destinationNodeId: number): Promise<boolean>;

Ask the controller to automatically assign to node nodeId a set of routes to node destinationNodeId.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/assignReturnRoutes/set

Payload:

{
	"args": [
		nodeId,
		destinationNodeId
	]
}

setPriorityRoute

async setPriorityRoute(
	nodeId: number,
	repeaters: number[],
	routeSpeed: ZWaveDataRate,
): Promise<boolean>;

Sets the priority route for a given node ID.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/setPriorityRoute/set

Payload:

{
	"args": [
		nodeId,
		repeaters,
		routeSpeed
	]
}

removePriorityRoute

async removePriorityRoute(nodeId: number): Promise<boolean>;

Remove priority route for a given node ID.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/removePriorityRoute/set

Payload:

{
	"args": [
		nodeId
	]
}

checkLifelineHealth

async checkLifelineHealth(
	nodeId: number,
	rounds = 5,
): Promise<LifelineHealthCheckSummary & { targetNodeId: number }>;

Check node lifeline health.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/checkLifelineHealth/set

Payload:

{
	"args": [
		nodeId,
		rounds
	]
}

checkRouteHealth

async checkRouteHealth(
	nodeId: number,
	targetNodeId: number,
	rounds = 5,
): Promise<RouteHealthCheckSummary & { targetNodeId: number }>;

Check node routes health.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/checkRouteHealth/set

Payload:

{
	"args": [
		nodeId,
		targetNodeId,
		rounds
	]
}

abortHealthCheck

abortHealthCheck(nodeId: number): void;

Aborts an ongoing health check if one is currently in progress.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/abortHealthCheck/set

Payload:

{
	"args": [
		nodeId
	]
}

isFailedNode

async isFailedNode(nodeId: number): Promise<boolean>;

Check if a node is failed.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/isFailedNode/set

Payload:

{
	"args": [
		nodeId
	]
}

removeFailedNode

async removeFailedNode(nodeId: number): Promise<void>;

Remove a failed node.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/removeFailedNode/set

Payload:

{
	"args": [
		nodeId
	]
}

refreshInfo

refreshInfo(nodeId: number, options?: RefreshInfoOptions): Promise<void>;

Re interview the node.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/refreshInfo/set

Payload:

{
	"args": [
		nodeId,
		options
	]
}

firmwareUpdateOTW

async firmwareUpdateOTW(
	file: FwFile,
): Promise<ControllerFirmwareUpdateResult>;

Used to trigger an update of controller FW.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/firmwareUpdateOTW/set

Payload:

{
	"args": [
		file
	]
}

updateFirmware

updateFirmware(
	nodeId: number,
	files: FwFile[],
): Promise<FirmwareUpdateResult>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/updateFirmware/set

Payload:

{
	"args": [
		nodeId,
		files
	]
}

abortFirmwareUpdate

async abortFirmwareUpdate(nodeId: number): Promise<void>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/abortFirmwareUpdate/set

Payload:

{
	"args": [
		nodeId
	]
}

dumpNode

dumpNode(nodeId: number): import("/home/daniel/GitProjects/zwave-js-ui/node_modules/zwave-js/build/lib/node/Dump").NodeDump;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/dumpNode/set

Payload:

{
	"args": [
		nodeId
	]
}

beginRebuildingRoutes

beginRebuildingRoutes(options?: RebuildRoutesOptions): boolean;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/beginRebuildingRoutes/set

Payload:

{
	"args": [
		options
	]
}

stopRebuildingRoutes

stopRebuildingRoutes(): boolean;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/stopRebuildingRoutes/set

Payload:

{
	"args": []
}

hardReset

async hardReset(): Promise<void>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/hardReset/set

Payload:

{
	"args": []
}

softReset

softReset(): Promise<void>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/softReset/set

Payload:

{
	"args": []
}

sendCommand

async sendCommand(
	ctx: {
		nodeId: number
		endpoint: number
		commandClass: CommandClasses | keyof typeof CommandClasses
	},
	command: string,
	args: any[],
): Promise<any>;

Send a custom CC command. Check available commands by selecting a CC here.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/sendCommand/set

Payload:

{
	"args": [
		ctx,
		command,
		args
	]
}

writeBroadcast

async writeBroadcast(
	valueId: ValueID,
	value: unknown,
	options?: SetValueAPIOptions,
): Promise<void>;

Send broadcast write request.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/writeBroadcast/set

Payload:

{
	"args": [
		valueId,
		value,
		options
	]
}

writeMulticast

async writeMulticast(
	nodes: number[],
	valueId: ZUIValueId,
	value: unknown,
	options?: SetValueAPIOptions,
): Promise<void>;

Send multicast write request to a group of nodes.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/writeMulticast/set

Payload:

{
	"args": [
		nodes,
		valueId,
		value,
		options
	]
}

writeValue

async writeValue(
	valueId: ZUIValueId,
	value: any,
	options?: SetValueAPIOptions,
): Promise<SetValueResult>;

Set a value of a specific zwave valueId.

Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/writeValue/set

Payload:

{
	"args": [
		valueId,
		value,
		options
	]
}

grantSecurityClasses

grantSecurityClasses(requested: InclusionGrant): void;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/grantSecurityClasses/set

Payload:

{
	"args": [
		requested
	]
}

validateDSK

validateDSK(dsk: string): void;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/validateDSK/set

Payload:

{
	"args": [
		dsk
	]
}

abortInclusion

abortInclusion(): void;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/abortInclusion/set

Payload:

{
	"args": []
}

backupNVMRaw

async backupNVMRaw(): Promise<{ data: Buffer; fileName: string; }>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/backupNVMRaw/set

Payload:

{
	"args": []
}

restoreNVM

async restoreNVM(data: Buffer, useRaw = false): Promise<void>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/restoreNVM/set

Payload:

{
	"args": [
		data,
		useRaw
	]
}

getProvisioningEntries

async getProvisioningEntries(): Promise<SmartStartProvisioningEntry[]>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getProvisioningEntries/set

Payload:

{
	"args": []
}

getProvisioningEntry

getProvisioningEntry(dsk: string): SmartStartProvisioningEntry | undefined;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/getProvisioningEntry/set

Payload:

{
	"args": [
		dsk
	]
}

unprovisionSmartStartNode

unprovisionSmartStartNode(dskOrNodeId: string | number): void;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/unprovisionSmartStartNode/set

Payload:

{
	"args": [
		dskOrNodeId
	]
}

parseQRCodeString

parseQRCodeString(qrString: string): {
	parsed?: QRProvisioningInformation
	nodeId?: number
	exists: boolean
};
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/parseQRCodeString/set

Payload:

{
	"args": [
		qrString
	]
}

provisionSmartStartNode

provisionSmartStartNode(entry: PlannedProvisioningEntry | string): PlannedProvisioningEntry;
Mqtt usage

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

Payload:

{
	"args": [
		entry
	]
}

updateControllerNodeProps

async updateControllerNodeProps(
	node?: ZUINode,
	props: Array<'powerlevel' | 'RFRegion'> = ['powerlevel', 'RFRegion'],
): Promise<void>;
Mqtt usage

Topic: zwave/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/api/updateControllerNodeProps/set

Payload:

{
	"args": [
		node,
		props
	]
}

Set values

To write a value using MQTT you need to send a packet to the same topic where the value updates are published and adding the suffix /set.

Example:

To set the light dimmer of the node named light and location office to 100.

zwave/office/test/38/0/targetValue/set

Payload:

{
	"value": 100
}

To check if the value has been successfully write just check when the value changes on the topic:

zwave/office/test/38/0/targetValue

In this case the Command Class 38 (Multilevel Switch) also has a currentValue property that rappresents the current value of the device, MQTT also allows you to write to this valueId even if it is marked as read-only because it will redirect the write request to the associated targetValue. So the same payload sent to:

zwave/office/test/38/0/currentValue/set

Will work in the same way.

Set with options

If you would like to send a write request with options like transitionDurtation and volume you can do it by using a JSON payload:

Topic: zwave/office/light/38/0/targetValue/set

Payload:

{
	"value": 100,
	"options": {
		"transitionDuration": "5s"
	}
}

Example setting a value

Here is an example of sending a set command to a valueId using MQTT Explorer

MQTT Explorer

Broadcast

You can send two kind of broadcast requests:

  1. Send it to all values with a specific suffix in the network.

[!NOTE] This creates a LOT of traffic and can have a significant performance impact.

Topic: <mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/broadcast/<value_topic_suffix>/set

  • value_topic_suffix: the suffix of the topic of the value you want to control using broadcast.

It works like the set value API without the node name and location properties. If the API is correctly called the same payload of the request will be published to the topic without /set suffix.

Example of broadcast command (gateway configured as named topics):

zwave/_CLIENTS/ZWAVE_GATEWAY-test/broadcast/38/0/targetValue/set

Payload: 25.5

All nodes with a valueId Command class 38 (Multilevel Switch), Endpoint 0 will receive a write request of value 25.5 to property targetValue and will get the same value (as feedback) on the topic:

zwave/_CLIENTS/ZWAVE_GATEWAY-test/broadcast/38/0/targetValue

  1. Send a real zwave broadcast request

Topic: <mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/broadcast/set Payload:

{
  "commandClass": 38,
  "endpoint": 0,
  "property": "targetValue",
  "value": 80
}

Multicast

Send a multicast request to all nodes specified in the array in the payload. If this fails because it's not supported a fallback will try to send multiple single requests.

[!NOTE] Multicast requests have no delay between individual nodes reactions

Topic: <mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/multicast/set Payload:

{
  "nodes": [2, 3, 4, 6]
  "commandClass": 38,
  "endpoint": 0,
  "property": "targetValue",
  "value": 80
}

Special topics

App version

<mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/version

The payload will be in the time-value json format and the value will contain the app string version.

MQTT status

<mqtt_prefix>/_CLIENTS/ZWAVE_GATEWAY-<mqtt_name>/status

The payload will be in the time-value json format and the value will be true when mqtt is connected, false otherwise.

Node status

<mqtt_prefix>/<?node_location>/<node_name>/status

The payload will be true if node is ready false otherwise. If the payload is in JSON format it will also contain the node status string in status property (Alive, Awake, Dead).

Node Last Active

<mqtt_prefix>/<?node_location>/<node_name>/lastActive

The payload will be the timestamp of last time a packet is received by controller from this node.

Node information

<mqtt_prefix>/<?node_location>/<node_name>/nodeinfo

Payload includes all node details except Discovered devices, values and properties. Updates on every node change.

A example of payload is:

{
	"id": 97,
	"deviceId": "271-4098-2049",
	"manufacturer": "Fibargroup",
	"manufacturerId": 271,
	"productType": 2049,
	"productId": 4098,
	"name": "Sensor",
	"loc": "Hallway",
	"neighbors": [29, 43, 63, 64, 65, 66, 67, 72, 74, 86],
	"ready": true,
	"available": true,
	"failed": false,
	"lastActive": 1610009585743,
	"firmwareVersion": "3.3",
	"supportsBeaming": true,
	"isSecure": false,
	"keepAwake": false,
	"maxBaudRate": null,
	"isRouting": true,
	"isFrequentListening": false,
	"isListening": false,
	"status": "Asleep",
	"interviewStage": "Complete",
	"productLabel": "FGMS001",
	"productDescription": "Motion Sensor",
	"zwaveVersion": 4,
	"deviceClass": {
		"basic": 4,
		"generic": 7,
		"specific": 1
	},
	"hexId": "0x010f-0x1002-0x0801"
}

Node notifications

Node notifications are translated to valueIds based on the CC that is triggering the notification and the notification args. Topic and payload depends on your gateway settings.

Entry CC

ValueId:

 {
    ...
    property: args.eventType
    propertyKey: args.dataType
  }

Data: args.eventData

Notification CC

ValueId:

 {
    ...
    property: args.label
    propertyKey: args.eventLabel
  }

Data: args.parameters

Buffer payloads

When an MQTT message contains a value of type Buffer, such as an Api call argument or return value, the buffer's content is represented as a JSON object of this form:

{ "type": "Buffer", "data": [1, 2, 3] }