@camstack/addon-provider-hikvision 1.2.118 → 1.2.120

package/dist/addon.js

@@ -5367,7 +5367,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-BDR76Ykr.mjs
+//#region ../types/dist/sleep-vl6nBE8d.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -31371,14 +31371,81 @@ function summarisePrivacyAudio(profiles) {
 	if (profiles.length === 0) return null;
 	return profiles.some((p) => p.audioEnabled);
 }
+/**
+* What a preset id DOES on this camera.
+*
+* On several PTZ firmwares the preset namespace is shared: low ids are stored
+* positions, a reserved band triggers camera FUNCTIONS. The dispensa camera
+* (Hikvision) returns its own reserved band in the preset list, named by the
+* firmware:
+*
+*   34 Back to origin · 39 Day mode · 40 Night mode · 46 Day/Night Auto Mode
+*   92 Set manual limits · 93 Save manual limits · 94 Remote reboot
+*   95 Call OSD menu
+*
+* We used to hand all of these to the UI as ordinary presets. Saving over one
+* is what produced `PUT /ISAPI/PTZCtrl/channels/1/presets/34 -> HTTP 500`: the
+* camera refusing to let "Back to origin" be overwritten, surfaced to the
+* operator as a transport failure.
+*
+* A function preset stays fully usable as a DESTINATION -- `goToPreset('34')`
+* is the single most useful thing that camera can do. Only `savePreset` and
+* `deletePreset` are gated.
+*/
+var PtzPresetFunctionSchema = _enum([
+	"home",
+	"day-mode",
+	"night-mode",
+	"day-night-auto",
+	"set-limits",
+	"save-limits",
+	"reboot",
+	"osd-menu"
+]);
 var PtzPresetSchema = object({
 	id: string(),
-	name: string()
+	name: string(),
+	/**
+	* The firmware function this id performs, when the provider KNOWS the id is
+	* reserved. `null` = an ordinary stored position, OR a reserved id this
+	* provider does not recognise -- the two are told apart by `writable`.
+	*/
+	fn: PtzPresetFunctionSchema.nullable(),
+	/**
+	* Whether `savePreset` / `deletePreset` may target this id. A provider sets
+	* it false only for a band it KNOWS is reserved; where the firmware is not
+	* documented it stays true and a refusal comes from the camera, named.
+	*/
+	writable: boolean()
 });
+/**
+* Where the head is pointing -- per axis, and `null` when the driver cannot
+* read it.
+*
+* It used to be three REQUIRED numbers, which left a provider that cannot read
+* position no way to say so. All four said `0`:
+*
+*   reolink   `return { pan: 0, tilt: 0, zoom: 0 }`  "until a position-query
+*                                                     path lands upstream"
+*   hikvision stub, "firmware-dependent and frequently absent"
+*   amcrest   stub, "no generic absolute-position read for this model family"
+*   onvif     throws
+*
+* So every consumer asking where a camera points was told "perfectly centred"
+* by four cameras that had never looked. That is D393 -- a measurement that
+* FAILED is `null`, never `0`, and the type says so all the way to the
+* decision -- the same shape as the unreadable `statfs` folded into "0 bytes of
+* headroom", which evacuated a healthy disk.
+*
+* D393 also says to check for a narrower structural TWIN of the result type.
+* There is one: `PtzStatusSchema` extends this, so the lie had already
+* propagated into `getStatus`, which is the surface `getPosition`'s own comment
+* tells callers to migrate to.
+*/
 var PtzPositionSchema = object({
-	pan: number(),
-	tilt: number(),
-	zoom: number()
+	pan: number().nullable(),
+	tilt: number().nullable(),
+	zoom: number().nullable()
 });
 var PtzMoveCommandSchema = object({
 	pan: number().optional(),
@@ -31400,7 +31467,72 @@ var PtzOptionsSchema = object({
 	maxPresets: number().optional(),
 	/** Whether the camera exposes a controllable autofocus toggle
 	*  (boolean `hasX` per the getOptions availability convention). */
-	hasAutofocus: boolean()
+	hasAutofocus: boolean(),
+	/**
+	* How many distinct speeds this camera's NATIVE scale offers.
+	*
+	* The cap's `speed` is normalized 0..1 and each provider maps it down --
+	* Baichuan 1..63, Dahua 1..8, ISAPI's percentage -100..100. The normalized
+	* value hides how coarse that really is: asking an amcrest for `0.37` is
+	* meaningless, because it has eight steps and three of them round to the
+	* same one. A loop that tunes its own gain has to know the granularity of
+	* the knob it is turning.
+	*
+	* `null` = the driver does not know, or the scale is continuous (ONVIF takes
+	* a float). Never a made-up number.
+	*/
+	speedSteps: number().int().positive().nullable(),
+	/**
+	* How long ONE `move` pulse runs on this driver, ms.
+	*
+	* `move` is a self-terminating burst everywhere, but every provider hardcoded
+	* its own duration in private -- 200 reolink, 350 amcrest, 500 hikvision,
+	* 1000 onvif -- so no caller could read it. It is the DENOMINATOR of "how far
+	* did the head travel per pulse": without it a measured displacement has no
+	* gain to be divided into.
+	*
+	* `null` = the driver cannot say.
+	*/
+	moveImpulseMs: number().int().positive().nullable()
+});
+/**
+* Which preset `goHome` goes to, and WHO decided.
+*
+* `goHome` used to be three vendor "conventions" written in three comments --
+* Reolink preset 0, Hikvision preset '1', Dahua preset 1 -- and on this fleet
+* not one of the three cameras honours its own:
+*
+*   592  Videocamera camera Daniel (reolink)   preset 0 holds "stanza"
+*   1438 Videocamera dispensa (hikvision)      preset 1 holds "Credenza"
+*   3836 Videocamera studio (amcrest)          preset 1 holds "Preset1"
+*
+* So `goHome` meant "go wherever the operator happened to save in slot 0 or 1",
+* and two of the three swallowed the failure in a bare `catch`. For autotrack
+* this is the HOTTEST path -- it runs every time a subject is released -- so it
+* needs an answer that is true per camera and audible when it is missing.
+*
+* `source` is what makes it honest:
+*   - `operator` -- picked in the UI, stored by the provider.
+*   - `firmware` -- the camera itself named a preset `fn: 'home'` (Hikvision's
+*     "Back to origin"), adopted as the default with nothing to configure.
+*   - `native`   -- the driver homes WITHOUT a preset at all. ONVIF does:
+*     `goHome` is `ptzAbsoluteMove({x:0, y:0, zoom:0})`. `presetId` is null and
+*     that is not a failure -- there is nothing to pick, and the UI must offer
+*     no picker.
+*   - `none`     -- nothing is configured and the camera names nothing.
+*     `goHome` REFUSES rather than moving the head somewhere arbitrary.
+*
+* `source === 'none'` is the refusal condition, NOT `presetId === null`: the
+* native case has no preset and homes perfectly well.
+*/
+var PtzHomePresetSchema = object({
+	presetId: string().nullable(),
+	source: _enum([
+		"operator",
+		"firmware",
+		"native",
+		"none"
+	])
 });
 var ptzCapability = {
 	name: "ptz",
@@ -31441,7 +31573,66 @@ var ptzCapability = {
 			auth: "admin"
 		}),
 		getOptions: method(object({ deviceId: number() }), PtzOptionsSchema),
+		/**
+		* Move to the camera's configured home preset. THROWS when
+		* `getHomePreset()` resolves to `none` -- a head that did not move must
+		* never look like a head that went home.
+		*/
 		goHome: method(object({ deviceId: number() }), _void(), { kind: "mutation" }),
+		/** Which preset `goHome` targets, and who decided it. */
+		getHomePreset: method(object({ deviceId: number() }), PtzHomePresetSchema),
+		/**
+		* Pin the home preset for this camera. `null` clears the operator's choice
+		* and falls back to whatever the firmware names, or to `none`.
+		*/
+		setHomePreset: method(object({
+			deviceId: number(),
+			presetId: string().nullable()
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Make WHERE THE HEAD IS POINTING RIGHT NOW this camera's home.
+		*
+		* `setHomePreset` takes a preset id, and a preset id is the wrong shape for
+		* the most natural thing an operator does: aim the camera, then say "here".
+		* It is also the only shape a camera whose home is NOT a preset can accept
+		* -- Reolink's home is a guard point, a stored position with no id at all,
+		* and hiding the control for that case (as the UI briefly did) left the one
+		* vendor with a native home unable to set it.
+		*
+		* Each provider does it its own way:
+		*   reolink   `setGrd` with `needSetPos`, pinning the guard point here
+		*   hikvision / amcrest  save a preset, then pin it as home
+		*   onvif     REFUSES -- its home is the PTZ origin and cannot be moved
+		*
+		* A provider that cannot honour it throws rather than silently doing
+		* nothing: an operator who pressed "set home here" and saw no error would
+		* believe it took.
+		*/
+		captureHomeHere: method(object({ deviceId: number() }), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* How long the camera waits, idle, before returning home on its own --
+		* `null` when it has no such behaviour.
+		*
+		* Reolink's guard point carries one (`timeout`, freely settable in
+		* seconds). It is a real function of the camera that we did not expose at
+		* all, and it belongs next to the home it governs rather than in a vendor
+		* settings page nobody associates with Home.
+		*/
+		getHomeReturnSeconds: method(object({ deviceId: number() }), number().int().nullable()),
+		/** Set the idle-return delay. Refused by a camera that has no such timer. */
+		setHomeReturnSeconds: method(object({
+			deviceId: number(),
+			seconds: number().int().min(0).max(3600)
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/**
 		* Pull the current PTZ position. Redundant with the auto-injected
 		* `getStatus` method (see `status` below); kept for callers that
@@ -41155,6 +41346,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"ptz.captureHomeHere": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"ptz.continuousMove": {
 		capName: "ptz",
 		capScope: "device",
@@ -41167,6 +41364,18 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"ptz.getHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"ptz.getHomeReturnSeconds": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"ptz.getOptions": {
 		capName: "ptz",
 		capScope: "device",
@@ -41215,6 +41424,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"ptz.setHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
+	"ptz.setHomeReturnSeconds": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"ptz.stop": {
 		capName: "ptz",
 		capScope: "device",
@@ -44378,6 +44599,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.captureHomeHere": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.continuousMove": [{
 		name: "deviceId",
 		form: "single",
@@ -44388,6 +44614,16 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.getHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
+	"ptz.getHomeReturnSeconds": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.getOptions": [{
 		name: "deviceId",
 		form: "single",
@@ -44428,6 +44664,16 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.setHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
+	"ptz.setHomeReturnSeconds": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.stop": [{
 		name: "deviceId",
 		form: "single",
@@ -49736,6 +49982,110 @@ function buildRawState(reader) {
 	};
 }
 //#endregion
+//#region src/isapi-ptz-speed.ts
+/**
+* Turn the cap's normalized direction + magnitude into an ISAPI continuous
+* speed.
+*
+* The `ptz` cap splits the two: `pan`/`tilt`/`zoom` are a DIRECTION in -1..1,
+* and `speed` is the magnitude in 0..1. reolink maps them to Baichuan 1..63,
+* amcrest to Dahua 1..8 — and hikvision used to map them to nothing at all. It
+* dropped `speed` before it left the provider and handed the raw direction to
+* `/ISAPI/PTZCtrl/channels/{cam}/continuous`, whose `<pan>` is a speed
+* PERCENTAGE in -100..100.
+*
+* So `usePTZ` sending its d-pad default (`pan: 1, speed: 0.5`) reached the
+* dispensa camera as `<pan>1</pan>`: one percent of the camera's speed. A
+* request at less than half magnitude rounded to `0` and produced no motion at
+* all.
+*
+* An absent `speed` is mid-scale, never zero — reolink defaults to 32 of 63 for
+* the same reason. A caller who did not state a magnitude asked to move, not to
+* stand still.
+*/
+var MID_SCALE = .5;
+function isapiSpeedFor(direction, speed) {
+	const d = direction ?? 0;
+	if (!Number.isFinite(d) || d === 0) return 0;
+	const magnitude = speed === void 0 || !Number.isFinite(speed) ? MID_SCALE : Math.abs(speed);
+	const percent = Math.round(Math.sign(d) * Math.min(1, Math.abs(d)) * Math.min(1, magnitude) * 100);
+	return Math.max(-100, Math.min(100, percent));
+}
+//#endregion
+//#region src/ptz-preset-functions.ts
+var RESERVED = new Map([
+	["34", "home"],
+	["39", "day-mode"],
+	["40", "night-mode"],
+	["46", "day-night-auto"],
+	["92", "set-limits"],
+	["93", "save-limits"],
+	["94", "reboot"],
+	["95", "osd-menu"]
+]);
+/** The firmware function this id performs, or `null` for a stored position. */
+function presetFunctionFor(presetId) {
+	return RESERVED.get(presetId) ?? null;
+}
+/**
+* Whether `savePreset` / `deletePreset` may target this id.
+*
+* Anything outside the known band stays writable: an undocumented firmware
+* must be allowed to refuse for itself rather than be guessed at here.
+*/
+function isPresetWritable(presetId) {
+	return !RESERVED.has(presetId);
+}
+/**
+* Refuse a write to a reserved id, naming the function that owns it.
+*
+* Extracted so the REFUSAL itself is assertable. With the check inline in
+* `savePreset` / `deletePreset`, deleting it left every test green -- the table
+* spec proves what the band IS, not that anything consults it.
+*/
+function assertPresetWritable(presetId, action) {
+	const fn = presetFunctionFor(presetId);
+	if (fn === null) return;
+	throw new Error(`Preset ${presetId} is a firmware function on this camera (${fn}) and cannot be ${action}` + (action === "overwritten" ? " — pick an unreserved id" : ""));
+}
+//#endregion
+//#region src/free-preset-slot.ts
+/**
+* The lowest preset id this camera will actually accept a write on.
+*
+* "Set home here" has to land somewhere, and on a camera whose home IS a preset
+* that means claiming a slot. Two things make the choice non-obvious:
+*
+*  - the reserved FUNCTION band shares the preset namespace (34 "Back to
+*    origin", 94 "Remote reboot", 95 "Call OSD menu" and friends), and writing
+*    one answers HTTP 500;
+*  - the operator's own presets must not be overwritten, ever. Losing
+*    "Credenza" to make room for a home is a worse trade than refusing.
+*
+* So: the first id that is neither taken nor reserved, within the camera's
+* advertised budget. `null` when there is no room, and the caller must then
+* REFUSE rather than pick a victim.
+*/
+function findFreePresetSlot(taken, maxPresets) {
+	const used = new Set(taken.map((p) => p.id));
+	const ceiling = maxPresets === void 0 ? 32 : Math.min(maxPresets, 300);
+	for (let id = 1; id <= ceiling; id += 1) {
+		const candidate = String(id);
+		if (used.has(candidate)) continue;
+		if (!isPresetWritable(candidate)) continue;
+		return candidate;
+	}
+	return null;
+}
+/**
+* The name written on a preset claimed by "set home here".
+*
+* Named rather than left a literal so the slot is recognisable in the camera's
+* own web UI — an operator who finds an unexplained preset has no way to know
+* it is ours.
+*/
+var HOME_PRESET_NAME = "CamStack Home";
+//#endregion
 //#region src/schema.ts
 /**
 * Single source of truth for the addon id used in event-source tags +
@@ -50054,6 +50404,17 @@ var hikvisionCameraSchema = object({
 	*/
 	snapshotChannelId: string().default("").describe("ISAPI channel used for snapshots (empty = main stream)"),
 	/**
+	* Which preset `ptz.goHome` targets on THIS camera.
+	*
+	* Empty = no operator choice. The provider then falls back to the preset the
+	* FIRMWARE names as home (Hikvision returns id 34 "Back to origin" in its
+	* reserved band), and only if that is absent too does `goHome` refuse.
+	*
+	* It has to be stored because the vendor "convention" is wrong here: the code
+	* went to preset '1', and on the dispensa camera preset 1 is "Credenza".
+	*/
+	homePresetId: string().default("").describe("Preset id ptz.goHome targets (empty = use the firmware home)"),
+	/**
 	* Motion detection master switch + sensitivity (0..100). Maps to
 	* ISAPI `/ISAPI/System/Video/inputs/channels/{cam}/motionDetection`.
 	* Disabling this stops the camera from emitting `<eventType>VMD</eventType>`
@@ -51091,6 +51452,41 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 			...slice
 		} });
 	}
+	/**
+	* Which preset `goHome` targets, and who decided it.
+	*
+	* The operator's pick wins. With none, the FIRMWARE's own home is adopted --
+	* Hikvision names id 34 "Back to origin" in its reserved band -- so a camera
+	* that already knows where home is needs nothing configured. Only when both
+	* are absent is the answer `none`, and `goHome` then refuses rather than
+	* moving the head to an arbitrary slot.
+	*
+	* A failed preset read yields `none`, never a guess: an unreadable camera is
+	* not evidence that preset 34 exists (D393).
+	*/
+	async resolveHomePreset() {
+		const chosen = this.config.get("homePresetId") ?? "";
+		if (chosen !== "") return {
+			presetId: chosen,
+			source: "operator"
+		};
+		try {
+			const firmwareHome = (await this.ensureClient().listPtzPresets(1)).find((preset) => presetFunctionFor(preset.id) === "home");
+			if (firmwareHome !== void 0) return {
+				presetId: firmwareHome.id,
+				source: "firmware"
+			};
+		} catch (err) {
+			this.ctx.logger.warn("hikvision home preset lookup failed — goHome will refuse", {
+				tags: { deviceId: this.id },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+		}
+		return {
+			presetId: null,
+			source: "none"
+		};
+	}
 	/** Re-read the image-tuning snapshot from the camera and persist it.
 	*  Best-effort: a refresh failure is logged and swallowed so a save
 	*  never throws. Called after an Image-section push in
@@ -51367,12 +51763,12 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	registerPtzCap(cameraNumber) {
 		const isapi = this.ensureClient();
 		this.ctx.registerNativeCap(ptzCapability, {
-			move: async ({ deviceId, pan, tilt, zoom }) => {
+			move: async ({ deviceId, pan, tilt, zoom, speed }) => {
 				if (deviceId !== this.id) return;
 				await isapi.ptzContinuous(cameraNumber, {
-					pan,
-					tilt,
-					zoom
+					pan: isapiSpeedFor(pan, speed),
+					tilt: isapiSpeedFor(tilt, speed),
+					zoom: isapiSpeedFor(zoom, speed)
 				});
 				await new Promise((r) => setTimeout(r, 500));
 				await isapi.ptzContinuous(cameraNumber, {
@@ -51381,12 +51777,12 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					zoom: 0
 				});
 			},
-			continuousMove: async ({ deviceId, pan, tilt, zoom }) => {
+			continuousMove: async ({ deviceId, pan, tilt, zoom, speed }) => {
 				if (deviceId !== this.id) return;
 				await isapi.ptzContinuous(cameraNumber, {
-					pan,
-					tilt,
-					zoom
+					pan: isapiSpeedFor(pan, speed),
+					tilt: isapiSpeedFor(tilt, speed),
+					zoom: isapiSpeedFor(zoom, speed)
 				});
 			},
 			stop: async ({ deviceId }) => {
@@ -51401,7 +51797,9 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 				if (deviceId !== this.id) return [];
 				return (await isapi.listPtzPresets(cameraNumber)).map((p) => ({
 					id: p.id,
-					name: p.name ?? `Preset ${p.id}`
+					name: p.name ?? `Preset ${p.id}`,
+					fn: presetFunctionFor(p.id),
+					writable: isPresetWritable(p.id)
 				}));
 			},
 			goToPreset: async ({ deviceId, presetId }) => {
@@ -51410,10 +51808,12 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 			},
 			savePreset: async ({ deviceId, presetId, name }) => {
 				if (deviceId !== this.id) return;
+				assertPresetWritable(presetId, "overwritten");
 				await isapi.savePtzPreset(cameraNumber, presetId, name);
 			},
 			deletePreset: async ({ deviceId, presetId }) => {
 				if (deviceId !== this.id) return;
+				assertPresetWritable(presetId, "deleted");
 				await isapi.deletePtzPreset(cameraNumber, presetId);
 			},
 			getOptions: async ({ deviceId }) => {
@@ -51422,7 +51822,9 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					hasTilt: false,
 					hasZoom: false,
 					supportsPresets: false,
-					hasAutofocus: false
+					hasAutofocus: false,
+					speedSteps: 100,
+					moveImpulseMs: 500
 				};
 				const caps = await isapi.getPtzCapabilities(cameraNumber);
 				if (!caps) return {
@@ -51430,7 +51832,9 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					hasTilt: false,
 					hasZoom: false,
 					supportsPresets: false,
-					hasAutofocus: false
+					hasAutofocus: false,
+					speedSteps: 100,
+					moveImpulseMs: 500
 				};
 				const maxPresets = caps.maxPresetCount ?? void 0;
 				return {
@@ -51439,25 +51843,61 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					hasZoom: caps.hasZoom,
 					supportsPresets: maxPresets === void 0 ? true : maxPresets > 0,
 					hasAutofocus: false,
+					speedSteps: 100,
+					moveImpulseMs: 500,
 					...maxPresets !== void 0 ? { maxPresets } : {}
 				};
 			},
 			goHome: async ({ deviceId }) => {
 				if (deviceId !== this.id) return;
-				await isapi.ptzGoToPreset(cameraNumber, "1");
+				const home = await this.resolveHomePreset();
+				if (home.source === "none" || home.presetId === null) throw new Error("No home preset configured for this camera — set one in the PTZ settings");
+				await isapi.ptzGoToPreset(cameraNumber, home.presetId);
+			},
+			getHomePreset: async ({ deviceId }) => {
+				if (deviceId !== this.id) return {
+					presetId: null,
+					source: "none"
+				};
+				return this.resolveHomePreset();
+			},
+			captureHomeHere: async ({ deviceId }) => {
+				if (deviceId !== this.id) return;
+				const [presets, caps] = await Promise.all([isapi.listPtzPresets(cameraNumber), isapi.getPtzCapabilities(cameraNumber)]);
+				const slot = findFreePresetSlot(presets.map((p) => ({
+					id: p.id,
+					writable: isPresetWritable(p.id)
+				})), caps?.maxPresetCount ?? void 0);
+				if (slot === null) throw new Error("No free preset slot on this camera to store a home position — free one first");
+				await isapi.savePtzPreset(cameraNumber, slot, HOME_PRESET_NAME);
+				await this.config.setAll({ homePresetId: slot });
+				this.ctx.logger.info("hikvision: home pinned to the current position", {
+					tags: { deviceId: this.id },
+					meta: { presetId: slot }
+				});
+			},
+			getHomeReturnSeconds: async () => {
+				return null;
+			},
+			setHomeReturnSeconds: async () => {
+				throw new Error("Hikvision: the idle-return timer is not wired on this driver");
+			},
+			setHomePreset: async ({ deviceId, presetId }) => {
+				if (deviceId !== this.id) return;
+				await this.config.setAll({ homePresetId: presetId ?? "" });
 			},
 			getPosition: async () => {
 				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0
+					pan: null,
+					tilt: null,
+					zoom: null
 				};
 			},
 			getStatus: async () => {
 				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0,
+					pan: null,
+					tilt: null,
+					zoom: null,
 					autofocus: false
 				};
 			},

package/dist/addon.mjs

@@ -5368,7 +5368,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-BDR76Ykr.mjs
+//#region ../types/dist/sleep-vl6nBE8d.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -31372,14 +31372,81 @@ function summarisePrivacyAudio(profiles) {
 	if (profiles.length === 0) return null;
 	return profiles.some((p) => p.audioEnabled);
 }
+/**
+* What a preset id DOES on this camera.
+*
+* On several PTZ firmwares the preset namespace is shared: low ids are stored
+* positions, a reserved band triggers camera FUNCTIONS. The dispensa camera
+* (Hikvision) returns its own reserved band in the preset list, named by the
+* firmware:
+*
+*   34 Back to origin · 39 Day mode · 40 Night mode · 46 Day/Night Auto Mode
+*   92 Set manual limits · 93 Save manual limits · 94 Remote reboot
+*   95 Call OSD menu
+*
+* We used to hand all of these to the UI as ordinary presets. Saving over one
+* is what produced `PUT /ISAPI/PTZCtrl/channels/1/presets/34 -> HTTP 500`: the
+* camera refusing to let "Back to origin" be overwritten, surfaced to the
+* operator as a transport failure.
+*
+* A function preset stays fully usable as a DESTINATION -- `goToPreset('34')`
+* is the single most useful thing that camera can do. Only `savePreset` and
+* `deletePreset` are gated.
+*/
+var PtzPresetFunctionSchema = _enum([
+	"home",
+	"day-mode",
+	"night-mode",
+	"day-night-auto",
+	"set-limits",
+	"save-limits",
+	"reboot",
+	"osd-menu"
+]);
 var PtzPresetSchema = object({
 	id: string(),
-	name: string()
+	name: string(),
+	/**
+	* The firmware function this id performs, when the provider KNOWS the id is
+	* reserved. `null` = an ordinary stored position, OR a reserved id this
+	* provider does not recognise -- the two are told apart by `writable`.
+	*/
+	fn: PtzPresetFunctionSchema.nullable(),
+	/**
+	* Whether `savePreset` / `deletePreset` may target this id. A provider sets
+	* it false only for a band it KNOWS is reserved; where the firmware is not
+	* documented it stays true and a refusal comes from the camera, named.
+	*/
+	writable: boolean()
 });
+/**
+* Where the head is pointing -- per axis, and `null` when the driver cannot
+* read it.
+*
+* It used to be three REQUIRED numbers, which left a provider that cannot read
+* position no way to say so. All four said `0`:
+*
+*   reolink   `return { pan: 0, tilt: 0, zoom: 0 }`  "until a position-query
+*                                                     path lands upstream"
+*   hikvision stub, "firmware-dependent and frequently absent"
+*   amcrest   stub, "no generic absolute-position read for this model family"
+*   onvif     throws
+*
+* So every consumer asking where a camera points was told "perfectly centred"
+* by four cameras that had never looked. That is D393 -- a measurement that
+* FAILED is `null`, never `0`, and the type says so all the way to the
+* decision -- the same shape as the unreadable `statfs` folded into "0 bytes of
+* headroom", which evacuated a healthy disk.
+*
+* D393 also says to check for a narrower structural TWIN of the result type.
+* There is one: `PtzStatusSchema` extends this, so the lie had already
+* propagated into `getStatus`, which is the surface `getPosition`'s own comment
+* tells callers to migrate to.
+*/
 var PtzPositionSchema = object({
-	pan: number(),
-	tilt: number(),
-	zoom: number()
+	pan: number().nullable(),
+	tilt: number().nullable(),
+	zoom: number().nullable()
 });
 var PtzMoveCommandSchema = object({
 	pan: number().optional(),
@@ -31401,7 +31468,72 @@ var PtzOptionsSchema = object({
 	maxPresets: number().optional(),
 	/** Whether the camera exposes a controllable autofocus toggle
 	*  (boolean `hasX` per the getOptions availability convention). */
-	hasAutofocus: boolean()
+	hasAutofocus: boolean(),
+	/**
+	* How many distinct speeds this camera's NATIVE scale offers.
+	*
+	* The cap's `speed` is normalized 0..1 and each provider maps it down --
+	* Baichuan 1..63, Dahua 1..8, ISAPI's percentage -100..100. The normalized
+	* value hides how coarse that really is: asking an amcrest for `0.37` is
+	* meaningless, because it has eight steps and three of them round to the
+	* same one. A loop that tunes its own gain has to know the granularity of
+	* the knob it is turning.
+	*
+	* `null` = the driver does not know, or the scale is continuous (ONVIF takes
+	* a float). Never a made-up number.
+	*/
+	speedSteps: number().int().positive().nullable(),
+	/**
+	* How long ONE `move` pulse runs on this driver, ms.
+	*
+	* `move` is a self-terminating burst everywhere, but every provider hardcoded
+	* its own duration in private -- 200 reolink, 350 amcrest, 500 hikvision,
+	* 1000 onvif -- so no caller could read it. It is the DENOMINATOR of "how far
+	* did the head travel per pulse": without it a measured displacement has no
+	* gain to be divided into.
+	*
+	* `null` = the driver cannot say.
+	*/
+	moveImpulseMs: number().int().positive().nullable()
+});
+/**
+* Which preset `goHome` goes to, and WHO decided.
+*
+* `goHome` used to be three vendor "conventions" written in three comments --
+* Reolink preset 0, Hikvision preset '1', Dahua preset 1 -- and on this fleet
+* not one of the three cameras honours its own:
+*
+*   592  Videocamera camera Daniel (reolink)   preset 0 holds "stanza"
+*   1438 Videocamera dispensa (hikvision)      preset 1 holds "Credenza"
+*   3836 Videocamera studio (amcrest)          preset 1 holds "Preset1"
+*
+* So `goHome` meant "go wherever the operator happened to save in slot 0 or 1",
+* and two of the three swallowed the failure in a bare `catch`. For autotrack
+* this is the HOTTEST path -- it runs every time a subject is released -- so it
+* needs an answer that is true per camera and audible when it is missing.
+*
+* `source` is what makes it honest:
+*   - `operator` -- picked in the UI, stored by the provider.
+*   - `firmware` -- the camera itself named a preset `fn: 'home'` (Hikvision's
+*     "Back to origin"), adopted as the default with nothing to configure.
+*   - `native`   -- the driver homes WITHOUT a preset at all. ONVIF does:
+*     `goHome` is `ptzAbsoluteMove({x:0, y:0, zoom:0})`. `presetId` is null and
+*     that is not a failure -- there is nothing to pick, and the UI must offer
+*     no picker.
+*   - `none`     -- nothing is configured and the camera names nothing.
+*     `goHome` REFUSES rather than moving the head somewhere arbitrary.
+*
+* `source === 'none'` is the refusal condition, NOT `presetId === null`: the
+* native case has no preset and homes perfectly well.
+*/
+var PtzHomePresetSchema = object({
+	presetId: string().nullable(),
+	source: _enum([
+		"operator",
+		"firmware",
+		"native",
+		"none"
+	])
 });
 var ptzCapability = {
 	name: "ptz",
@@ -31442,7 +31574,66 @@ var ptzCapability = {
 			auth: "admin"
 		}),
 		getOptions: method(object({ deviceId: number() }), PtzOptionsSchema),
+		/**
+		* Move to the camera's configured home preset. THROWS when
+		* `getHomePreset()` resolves to `none` -- a head that did not move must
+		* never look like a head that went home.
+		*/
 		goHome: method(object({ deviceId: number() }), _void(), { kind: "mutation" }),
+		/** Which preset `goHome` targets, and who decided it. */
+		getHomePreset: method(object({ deviceId: number() }), PtzHomePresetSchema),
+		/**
+		* Pin the home preset for this camera. `null` clears the operator's choice
+		* and falls back to whatever the firmware names, or to `none`.
+		*/
+		setHomePreset: method(object({
+			deviceId: number(),
+			presetId: string().nullable()
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Make WHERE THE HEAD IS POINTING RIGHT NOW this camera's home.
+		*
+		* `setHomePreset` takes a preset id, and a preset id is the wrong shape for
+		* the most natural thing an operator does: aim the camera, then say "here".
+		* It is also the only shape a camera whose home is NOT a preset can accept
+		* -- Reolink's home is a guard point, a stored position with no id at all,
+		* and hiding the control for that case (as the UI briefly did) left the one
+		* vendor with a native home unable to set it.
+		*
+		* Each provider does it its own way:
+		*   reolink   `setGrd` with `needSetPos`, pinning the guard point here
+		*   hikvision / amcrest  save a preset, then pin it as home
+		*   onvif     REFUSES -- its home is the PTZ origin and cannot be moved
+		*
+		* A provider that cannot honour it throws rather than silently doing
+		* nothing: an operator who pressed "set home here" and saw no error would
+		* believe it took.
+		*/
+		captureHomeHere: method(object({ deviceId: number() }), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* How long the camera waits, idle, before returning home on its own --
+		* `null` when it has no such behaviour.
+		*
+		* Reolink's guard point carries one (`timeout`, freely settable in
+		* seconds). It is a real function of the camera that we did not expose at
+		* all, and it belongs next to the home it governs rather than in a vendor
+		* settings page nobody associates with Home.
+		*/
+		getHomeReturnSeconds: method(object({ deviceId: number() }), number().int().nullable()),
+		/** Set the idle-return delay. Refused by a camera that has no such timer. */
+		setHomeReturnSeconds: method(object({
+			deviceId: number(),
+			seconds: number().int().min(0).max(3600)
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/**
 		* Pull the current PTZ position. Redundant with the auto-injected
 		* `getStatus` method (see `status` below); kept for callers that
@@ -41156,6 +41347,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"ptz.captureHomeHere": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"ptz.continuousMove": {
 		capName: "ptz",
 		capScope: "device",
@@ -41168,6 +41365,18 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"ptz.getHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"ptz.getHomeReturnSeconds": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"ptz.getOptions": {
 		capName: "ptz",
 		capScope: "device",
@@ -41216,6 +41425,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"ptz.setHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
+	"ptz.setHomeReturnSeconds": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"ptz.stop": {
 		capName: "ptz",
 		capScope: "device",
@@ -44379,6 +44600,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.captureHomeHere": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.continuousMove": [{
 		name: "deviceId",
 		form: "single",
@@ -44389,6 +44615,16 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.getHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
+	"ptz.getHomeReturnSeconds": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.getOptions": [{
 		name: "deviceId",
 		form: "single",
@@ -44429,6 +44665,16 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.setHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
+	"ptz.setHomeReturnSeconds": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.stop": [{
 		name: "deviceId",
 		form: "single",
@@ -49737,6 +49983,110 @@ function buildRawState(reader) {
 	};
 }
 //#endregion
+//#region src/isapi-ptz-speed.ts
+/**
+* Turn the cap's normalized direction + magnitude into an ISAPI continuous
+* speed.
+*
+* The `ptz` cap splits the two: `pan`/`tilt`/`zoom` are a DIRECTION in -1..1,
+* and `speed` is the magnitude in 0..1. reolink maps them to Baichuan 1..63,
+* amcrest to Dahua 1..8 — and hikvision used to map them to nothing at all. It
+* dropped `speed` before it left the provider and handed the raw direction to
+* `/ISAPI/PTZCtrl/channels/{cam}/continuous`, whose `<pan>` is a speed
+* PERCENTAGE in -100..100.
+*
+* So `usePTZ` sending its d-pad default (`pan: 1, speed: 0.5`) reached the
+* dispensa camera as `<pan>1</pan>`: one percent of the camera's speed. A
+* request at less than half magnitude rounded to `0` and produced no motion at
+* all.
+*
+* An absent `speed` is mid-scale, never zero — reolink defaults to 32 of 63 for
+* the same reason. A caller who did not state a magnitude asked to move, not to
+* stand still.
+*/
+var MID_SCALE = .5;
+function isapiSpeedFor(direction, speed) {
+	const d = direction ?? 0;
+	if (!Number.isFinite(d) || d === 0) return 0;
+	const magnitude = speed === void 0 || !Number.isFinite(speed) ? MID_SCALE : Math.abs(speed);
+	const percent = Math.round(Math.sign(d) * Math.min(1, Math.abs(d)) * Math.min(1, magnitude) * 100);
+	return Math.max(-100, Math.min(100, percent));
+}
+//#endregion
+//#region src/ptz-preset-functions.ts
+var RESERVED = new Map([
+	["34", "home"],
+	["39", "day-mode"],
+	["40", "night-mode"],
+	["46", "day-night-auto"],
+	["92", "set-limits"],
+	["93", "save-limits"],
+	["94", "reboot"],
+	["95", "osd-menu"]
+]);
+/** The firmware function this id performs, or `null` for a stored position. */
+function presetFunctionFor(presetId) {
+	return RESERVED.get(presetId) ?? null;
+}
+/**
+* Whether `savePreset` / `deletePreset` may target this id.
+*
+* Anything outside the known band stays writable: an undocumented firmware
+* must be allowed to refuse for itself rather than be guessed at here.
+*/
+function isPresetWritable(presetId) {
+	return !RESERVED.has(presetId);
+}
+/**
+* Refuse a write to a reserved id, naming the function that owns it.
+*
+* Extracted so the REFUSAL itself is assertable. With the check inline in
+* `savePreset` / `deletePreset`, deleting it left every test green -- the table
+* spec proves what the band IS, not that anything consults it.
+*/
+function assertPresetWritable(presetId, action) {
+	const fn = presetFunctionFor(presetId);
+	if (fn === null) return;
+	throw new Error(`Preset ${presetId} is a firmware function on this camera (${fn}) and cannot be ${action}` + (action === "overwritten" ? " — pick an unreserved id" : ""));
+}
+//#endregion
+//#region src/free-preset-slot.ts
+/**
+* The lowest preset id this camera will actually accept a write on.
+*
+* "Set home here" has to land somewhere, and on a camera whose home IS a preset
+* that means claiming a slot. Two things make the choice non-obvious:
+*
+*  - the reserved FUNCTION band shares the preset namespace (34 "Back to
+*    origin", 94 "Remote reboot", 95 "Call OSD menu" and friends), and writing
+*    one answers HTTP 500;
+*  - the operator's own presets must not be overwritten, ever. Losing
+*    "Credenza" to make room for a home is a worse trade than refusing.
+*
+* So: the first id that is neither taken nor reserved, within the camera's
+* advertised budget. `null` when there is no room, and the caller must then
+* REFUSE rather than pick a victim.
+*/
+function findFreePresetSlot(taken, maxPresets) {
+	const used = new Set(taken.map((p) => p.id));
+	const ceiling = maxPresets === void 0 ? 32 : Math.min(maxPresets, 300);
+	for (let id = 1; id <= ceiling; id += 1) {
+		const candidate = String(id);
+		if (used.has(candidate)) continue;
+		if (!isPresetWritable(candidate)) continue;
+		return candidate;
+	}
+	return null;
+}
+/**
+* The name written on a preset claimed by "set home here".
+*
+* Named rather than left a literal so the slot is recognisable in the camera's
+* own web UI — an operator who finds an unexplained preset has no way to know
+* it is ours.
+*/
+var HOME_PRESET_NAME = "CamStack Home";
+//#endregion
 //#region src/schema.ts
 /**
 * Single source of truth for the addon id used in event-source tags +
@@ -50055,6 +50405,17 @@ var hikvisionCameraSchema = object({
 	*/
 	snapshotChannelId: string().default("").describe("ISAPI channel used for snapshots (empty = main stream)"),
 	/**
+	* Which preset `ptz.goHome` targets on THIS camera.
+	*
+	* Empty = no operator choice. The provider then falls back to the preset the
+	* FIRMWARE names as home (Hikvision returns id 34 "Back to origin" in its
+	* reserved band), and only if that is absent too does `goHome` refuse.
+	*
+	* It has to be stored because the vendor "convention" is wrong here: the code
+	* went to preset '1', and on the dispensa camera preset 1 is "Credenza".
+	*/
+	homePresetId: string().default("").describe("Preset id ptz.goHome targets (empty = use the firmware home)"),
+	/**
 	* Motion detection master switch + sensitivity (0..100). Maps to
 	* ISAPI `/ISAPI/System/Video/inputs/channels/{cam}/motionDetection`.
 	* Disabling this stops the camera from emitting `<eventType>VMD</eventType>`
@@ -51092,6 +51453,41 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 			...slice
 		} });
 	}
+	/**
+	* Which preset `goHome` targets, and who decided it.
+	*
+	* The operator's pick wins. With none, the FIRMWARE's own home is adopted --
+	* Hikvision names id 34 "Back to origin" in its reserved band -- so a camera
+	* that already knows where home is needs nothing configured. Only when both
+	* are absent is the answer `none`, and `goHome` then refuses rather than
+	* moving the head to an arbitrary slot.
+	*
+	* A failed preset read yields `none`, never a guess: an unreadable camera is
+	* not evidence that preset 34 exists (D393).
+	*/
+	async resolveHomePreset() {
+		const chosen = this.config.get("homePresetId") ?? "";
+		if (chosen !== "") return {
+			presetId: chosen,
+			source: "operator"
+		};
+		try {
+			const firmwareHome = (await this.ensureClient().listPtzPresets(1)).find((preset) => presetFunctionFor(preset.id) === "home");
+			if (firmwareHome !== void 0) return {
+				presetId: firmwareHome.id,
+				source: "firmware"
+			};
+		} catch (err) {
+			this.ctx.logger.warn("hikvision home preset lookup failed — goHome will refuse", {
+				tags: { deviceId: this.id },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+		}
+		return {
+			presetId: null,
+			source: "none"
+		};
+	}
 	/** Re-read the image-tuning snapshot from the camera and persist it.
 	*  Best-effort: a refresh failure is logged and swallowed so a save
 	*  never throws. Called after an Image-section push in
@@ -51368,12 +51764,12 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	registerPtzCap(cameraNumber) {
 		const isapi = this.ensureClient();
 		this.ctx.registerNativeCap(ptzCapability, {
-			move: async ({ deviceId, pan, tilt, zoom }) => {
+			move: async ({ deviceId, pan, tilt, zoom, speed }) => {
 				if (deviceId !== this.id) return;
 				await isapi.ptzContinuous(cameraNumber, {
-					pan,
-					tilt,
-					zoom
+					pan: isapiSpeedFor(pan, speed),
+					tilt: isapiSpeedFor(tilt, speed),
+					zoom: isapiSpeedFor(zoom, speed)
 				});
 				await new Promise((r) => setTimeout(r, 500));
 				await isapi.ptzContinuous(cameraNumber, {
@@ -51382,12 +51778,12 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					zoom: 0
 				});
 			},
-			continuousMove: async ({ deviceId, pan, tilt, zoom }) => {
+			continuousMove: async ({ deviceId, pan, tilt, zoom, speed }) => {
 				if (deviceId !== this.id) return;
 				await isapi.ptzContinuous(cameraNumber, {
-					pan,
-					tilt,
-					zoom
+					pan: isapiSpeedFor(pan, speed),
+					tilt: isapiSpeedFor(tilt, speed),
+					zoom: isapiSpeedFor(zoom, speed)
 				});
 			},
 			stop: async ({ deviceId }) => {
@@ -51402,7 +51798,9 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 				if (deviceId !== this.id) return [];
 				return (await isapi.listPtzPresets(cameraNumber)).map((p) => ({
 					id: p.id,
-					name: p.name ?? `Preset ${p.id}`
+					name: p.name ?? `Preset ${p.id}`,
+					fn: presetFunctionFor(p.id),
+					writable: isPresetWritable(p.id)
 				}));
 			},
 			goToPreset: async ({ deviceId, presetId }) => {
@@ -51411,10 +51809,12 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 			},
 			savePreset: async ({ deviceId, presetId, name }) => {
 				if (deviceId !== this.id) return;
+				assertPresetWritable(presetId, "overwritten");
 				await isapi.savePtzPreset(cameraNumber, presetId, name);
 			},
 			deletePreset: async ({ deviceId, presetId }) => {
 				if (deviceId !== this.id) return;
+				assertPresetWritable(presetId, "deleted");
 				await isapi.deletePtzPreset(cameraNumber, presetId);
 			},
 			getOptions: async ({ deviceId }) => {
@@ -51423,7 +51823,9 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					hasTilt: false,
 					hasZoom: false,
 					supportsPresets: false,
-					hasAutofocus: false
+					hasAutofocus: false,
+					speedSteps: 100,
+					moveImpulseMs: 500
 				};
 				const caps = await isapi.getPtzCapabilities(cameraNumber);
 				if (!caps) return {
@@ -51431,7 +51833,9 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					hasTilt: false,
 					hasZoom: false,
 					supportsPresets: false,
-					hasAutofocus: false
+					hasAutofocus: false,
+					speedSteps: 100,
+					moveImpulseMs: 500
 				};
 				const maxPresets = caps.maxPresetCount ?? void 0;
 				return {
@@ -51440,25 +51844,61 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 					hasZoom: caps.hasZoom,
 					supportsPresets: maxPresets === void 0 ? true : maxPresets > 0,
 					hasAutofocus: false,
+					speedSteps: 100,
+					moveImpulseMs: 500,
 					...maxPresets !== void 0 ? { maxPresets } : {}
 				};
 			},
 			goHome: async ({ deviceId }) => {
 				if (deviceId !== this.id) return;
-				await isapi.ptzGoToPreset(cameraNumber, "1");
+				const home = await this.resolveHomePreset();
+				if (home.source === "none" || home.presetId === null) throw new Error("No home preset configured for this camera — set one in the PTZ settings");
+				await isapi.ptzGoToPreset(cameraNumber, home.presetId);
+			},
+			getHomePreset: async ({ deviceId }) => {
+				if (deviceId !== this.id) return {
+					presetId: null,
+					source: "none"
+				};
+				return this.resolveHomePreset();
+			},
+			captureHomeHere: async ({ deviceId }) => {
+				if (deviceId !== this.id) return;
+				const [presets, caps] = await Promise.all([isapi.listPtzPresets(cameraNumber), isapi.getPtzCapabilities(cameraNumber)]);
+				const slot = findFreePresetSlot(presets.map((p) => ({
+					id: p.id,
+					writable: isPresetWritable(p.id)
+				})), caps?.maxPresetCount ?? void 0);
+				if (slot === null) throw new Error("No free preset slot on this camera to store a home position — free one first");
+				await isapi.savePtzPreset(cameraNumber, slot, HOME_PRESET_NAME);
+				await this.config.setAll({ homePresetId: slot });
+				this.ctx.logger.info("hikvision: home pinned to the current position", {
+					tags: { deviceId: this.id },
+					meta: { presetId: slot }
+				});
+			},
+			getHomeReturnSeconds: async () => {
+				return null;
+			},
+			setHomeReturnSeconds: async () => {
+				throw new Error("Hikvision: the idle-return timer is not wired on this driver");
+			},
+			setHomePreset: async ({ deviceId, presetId }) => {
+				if (deviceId !== this.id) return;
+				await this.config.setAll({ homePresetId: presetId ?? "" });
 			},
 			getPosition: async () => {
 				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0
+					pan: null,
+					tilt: null,
+					zoom: null
 				};
 			},
 			getStatus: async () => {
 				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0,
+					pan: null,
+					tilt: null,
+					zoom: null,
 					autofocus: false
 				};
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-hikvision",
-  "version": "1.2.118",
+  "version": "1.2.120",
   "description": "Hikvision camera device provider addon for CamStack — ISAPI over HTTP(S) with digest auth (snapshot, alarm stream, RTSP discovery)",
   "keywords": [
     "camstack",