Version: 3.5.x

Settings Reference

This document lists all settings returned by the /settings/ endpoint with their key, type (from type_hint), and constraints (from metadata.constraint.range + locked where applicable).

A locked setting is read-only at runtime. It can be changed via the config file or through the Haply Hub settings page, but a full service restart is required for changes to take effect. These are marked boot in the tables below.

Configuration

The configuration file to override the settings during service startup is located here:

Platform	Location
Windows	`C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json`
MacOS	`/Library/Application Support/Haply/Inverse/haply-inverse-service-config.json`
Linux	`/etc/haply-inverse-service/haply-inverse-service-config.json`

The config file is a flat JSON object mapping setting keys to override values. Keys must be valid settings keys returned by the /settings/ HTTP route (see API Reference). Any key not specified uses the service default.

For example, a networking configuration override:

{
  "communication/http/port": 8400,
  "communication/websocket/port": 8500,
  "communication/events/port": 9000,
  "communication/bind_all_interfaces": true
}

Type mapping

Type hints returned by the API map to these JSON shapes:

STRING → string
BOOL → bool
INT → int
FLOAT → float
ARR_STRING → string[]
VEC3 → vec3 (object with {x, y, z})
GENERIC → json (arbitrary structured value)

`communication/…`

Network ports and bind addresses for the HTTP, WebSocket, and event-stream servers. Most entries are boot-only.

Key	Type	Constraints	Description
`communication/serial/enabled`	`bool`	—	Enable or disable serial device communication.
`communication/bind_address`	`string`	boot	IP address the HTTP and WebSocket servers bind to.
`communication/bind_all_interfaces`	`bool`	boot	Bind servers to `0.0.0.0` instead of localhost.
`communication/http/port`	`int`	boot	HTTP REST API port (default `10000`).
`communication/websocket/port`	`int`	boot	Main v3.1 WebSocket port (default `10001`).
`communication/websocket/legacy_port`	`int`	boot	Legacy v3.0 WebSocket port (default `10000`).
`communication/events/port`	`int`	boot	Event-stream WebSocket port (default `10020`).

`devices/…`

`devices/detection/…`

Serial-port scanning policy. All entries are advanced.

Key	Type	Constraints	Description
`devices/detection/scan_period_ms`	`int`	range 100–10000; boot	Interval between serial port scans (ms).
`devices/detection/handshake_timeout_s`	`int`	range 1–15	Handshake timeout per port (s).
`devices/detection/max_retries`	`int`	range 1–10	Maximum handshake retry attempts per port.
`devices/detection/failure_log_delay_s`	`int`	range 1–60	Delay before re-logging a detection failure (s).
`devices/detection/block_looping_ports`	`bool`	—	Block device readiness when a looping port is detected.
`devices/detection/excluded_ports`	`json`	—	Serial port paths to skip during detection.
`devices/detection/additional_ports`	`string[]`	—	Extra serial port paths to scan unconditionally.
`devices/detection/allowed_vendor_id_filter`	`string[]`	—	USB vendor IDs allowed during port enumeration.
`devices/detection/port_name_substring_filter`	`string[]`	—	Platform-specific port name substrings to match.
`devices/detection/wireless_verse_grip_description_filter`	`string[]`	—	Port description substrings for wireless VerseGrip detection.
`devices/detection/inverse3x_description_filter`	`string[]`	—	Port description substrings for Inverse3x detection.
`devices/detection/extra_ports` (deprecated)	`string[]`	—	Use `devices/detection/additional_ports` instead. Reads and writes are transparently forwarded to the canonical key.

`devices/inverse*/…`

Global defaults applied to every Inverse3-family device. Per-session overrides take precedence.

Key	Type	Constraints	Description
`devices/inverse*/filters/force_scale/gain`	`float`	range 0.0–2.0	Global force output multiplier applied to all devices.
`devices/inverse*/filters/force_gate/gain`	`float`	range 0.0–1.0	Default force-gate gain for new sessions.
`devices/inverse*/control_timeout_ms`	`int`	range 50–10000	Timeout before releasing the device control lock (ms).
`devices/inverse*/query_orientation_on_idle`	`bool`	—	Query body orientation from firmware when the device is idle.

`devices/presets`

Key	Type	Constraints	Description
`devices/presets`	`json`	—	Default device-configuration presets per device type (mount transform, basis, etc. for `inverse_arm_front_`, `inverse_led_front_`, `minverse_*`, `verse_grip_default`, `wireless_verse_grip_default`, `custom_verse_grip_default`).

`devices/wireless_verse_grip/…`

Key	Type	Constraints	Description
`devices/wireless_verse_grip/battery/low_threshold`	`int`	—	Battery percentage below which a low-battery warning fires.
`devices/wireless_verse_grip/battery/critical_threshold`	`int`	—	Battery percentage below which a critical-battery alert fires.
`devices/wireless_verse_grip/battery/reset_margin`	`int`	—	Hysteresis margin before clearing a battery warning.
`devices/wireless_verse_grip/filters/orientation_filter`	`json`	boot	One Euro Filter config for wireless VerseGrip orientation.

`features/…`

`features/calibration/…`

Key	Type	Constraints	Description
`features/calibration/hall_threshold`	`int`	range 1–32	Hall sensor level at which the pen is considered attached during calibration.

`features/grip_hook/…`

Automatic grip-hook behaviour — locks the cursor while the grip is held upright.

Key	Type	Constraints	Description
`features/grip_hook/enabled`	`bool`	—	Enable grip-hook auto-lock when the grip is held upright.
`features/grip_hook/use_hall`	`bool`	—	Use the hall-sensor threshold instead of orientation for grip detection.
`features/grip_hook/hall`	`int`	range 1–32	Hall-sensor value threshold to trigger the grip lock.
`features/grip_hook/hold_duration`	`int`	range 10–1000	Duration to hold the lock after trigger (ms).

`features/navigation/bubble/…`

Bubble navigation module defaults — passed into the session when a bubble behaviour is first activated.

Key	Type	Constraints	Description
`features/navigation/bubble/center`	`vec3`	—	Default bubble centre position.
`features/navigation/bubble/max_velocity`	`float`	—	Maximum navigation velocity in the velocity zone (m/s).
`features/navigation/bubble/velocity_zone_width`	`float`	—	Width of the velocity zone outside the bubble surface (m).
`features/navigation/bubble/reset_velocity_on_entry`	`bool`	—	Reset velocity to zero when the cursor enters the bubble.
`features/navigation/bubble/spring_inner`	`float`	—	Spring coefficient at the bubble centre (N/m).
`features/navigation/bubble/spring_surface`	`float`	—	Spring coefficient at the bubble surface (N/m).
`features/navigation/bubble/spring_outer`	`float`	—	Spring coefficient at the outer boundary (N/m).
`features/navigation/bubble/damping_inner`	`float`	—	Damping coefficient at the bubble centre (Ns/m).
`features/navigation/bubble/damping_surface`	`float`	—	Damping coefficient at the bubble surface (Ns/m).
`features/navigation/bubble/damping_outer`	`float`	—	Damping coefficient at the outer boundary (Ns/m).
`features/navigation/bubble/wall_stiffness`	`float`	—	Stiffness of the hard wall at the outer boundary (N/m).
`features/navigation/bubble/bump_width`	`float`	—	Width of the tactile bump at the bubble surface (m).
`features/navigation/bubble/bump_stiffness`	`float`	—	Stiffness of the tactile bump at the bubble surface (N/m).

`features/safe_trajectory/…`

Velocity limiter for end-effector motion.

Key	Type	Constraints	Description
`features/safe_trajectory/enabled`	`bool`	—	Enable the safe-trajectory speed limiter.
`features/safe_trajectory/max_vel`	`float`	range 0.01–2.0	Maximum allowed end-effector velocity (m/s).

`features/screensaver/…`

Idle animation played on Inverse3 devices when no session is driving them.

Key	Type	Constraints	Description
`features/screensaver/enabled`	`bool`	—	Enable the idle screensaver animation on Inverse3 devices.
`features/screensaver/speed`	`float`	range 0.001–0.2	Screensaver animation speed.
`features/screensaver/distracted_speed`	`float`	range 0.001–0.2	Animation speed when the user is near but not engaging.

`features/sdf/…`

Signed-distance-field haptic effects module (SDF HFX).

Key	Type	Constraints	Description
`features/sdf/enabled`	`bool`	—	Enable or disable the SDF haptic-effects module.
`features/sdf/state_output`	`bool`	—	Include SDF state in the device output payloads by default.
`features/sdf/max_count`	`int`	range 0–128	Maximum number of active SDF effects (`0` = unlimited).
`features/sdf/events/created`	`bool`	—	Emit an event when a new SDF effect is created.
`features/sdf/events/deleted`	`bool`	—	Emit an event when an SDF effect is deleted.
`features/sdf/events/updated`	`bool`	—	Emit an event when an SDF effect is updated.
`features/sdf/probe_on_zero_force/enabled`	`bool`	—	Auto-probe SDF fields when applied force is near zero.
`features/sdf/probe_on_zero_force/delay`	`float`	range 0.001–60.0	Delay before auto-probing after force drops to zero (s).

`features/verse_grip_pairing/…`

Attach/detach tracking between an Inverse3 and a (wired or wireless) Verse Grip. Powers the Haply Hub pairing UI.

Key	Type	Constraints	Description
`features/verse_grip_pairing/enabled`	`bool`	—	Enable pairing / attach-detach tracking.
`features/verse_grip_pairing/hall_threshold_vg`	`int`	range 1–32	Hall level at which a wired VerseGrip is considered attached.
`features/verse_grip_pairing/hall_threshold_wvg`	`int`	range 1–32	Hall level at which a Wireless VerseGrip is considered attached.
`features/verse_grip_pairing/detach_debounce_ms`	`int`	range 0–1000	Debounce window before committing a detach (ms).
`features/verse_grip_pairing/heartbeat_ms`	`int`	range 100–10000	Interval between forced re-notifications (ms).
`features/verse_grip_pairing/force_attached`	`bool`	—	Permanently force the attached state to `true`, bypassing the hall sensor (hardware-failure workaround).

`serialization/…`

Transform-output formatting — affects WebSocket and HTTP JSON payloads.

Key	Type	Constraints	Description
`serialization/explicit_fields`	`bool`	—	Include transform fields that equal their identity default in serialized output (e.g. `position: {0,0,0}`, `rotation: {w:1,…}`). Useful when your client requires every field to be explicitly present. Default: `false`.
`serialization/force_complete_transforms`	`bool`	—	Always emit `position`, `rotation`, and `scale` in every transform output, including orientation-only devices (Verse Grip, Wireless Verse Grip) which otherwise emit only `rotation`. Subsumes `serialization/explicit_fields`. Default: `false`.

`session/…`

Session scheduler and command-pipeline limits.

Key	Type	Constraints	Description
`session/min_simulation_rate_hz`	`int`	range 20–500	Minimum acceptable device simulation rate (Hz) before a warning fires.
`session/commands/zoh_window_ms`	`int`	—	Zero-order-hold window — suppress probes received within this window (ms).
`session/commands/drop_warning_threshold`	`int`	—	Number of dropped commands within the window before warning.
`session/commands/drop_warning_window_ms`	`int`	—	Sliding window size for counting dropped commands (ms).
`session/commands/tick_on_empty_batch`	`bool`	—	Schedule a `main_loop` tick even when an entire WebSocket batch was dropped.

Configuration​

Type mapping​

communication/…​

devices/…​

devices/detection/…​

devices/inverse*/…​

devices/presets​

devices/wireless_verse_grip/…​

features/…​

features/calibration/…​

features/grip_hook/…​

features/navigation/bubble/…​

features/safe_trajectory/…​

features/screensaver/…​

features/sdf/…​

features/verse_grip_pairing/…​

serialization/…​

session/…​