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
}
Visibility and filtering
The /settings listing endpoints (GET /settings, GET /settings/) return only basic settings by default. Pass ?advanced=true to include settings flagged advanced, ?deprecated=true to include deprecated aliases. Hidden settings are reserved for internal use; they appear only when misc/hidden_settings is set via POST /settings/misc/hidden_settings (no query-param equivalent). Filter flags AND together — a key flagged both advanced and hidden needs both gates open. POST and DELETE on a known key are ungated.
Single-key reads (GET /settings/<key>) bypass the advanced/deprecated gate when you use the exact canonical key — useful for clients with prior knowledge. Hidden keys remain gated.
Three runtime toggles seed the gates; their values persist for the rest of the service lifetime:
| Key | Type | Constraints | Description |
|---|---|---|---|
misc/advanced_settings | bool | — | Include advanced-flagged settings in GET /settings listings (default false). Equivalent to passing ?advanced=true on every request. |
misc/deprecated_settings | bool | — | Include deprecated-flagged settings in GET /settings listings (default false). Equivalent to passing ?deprecated=true on every request. |
Type mapping
Type hints returned by the API map to these JSON shapes:
STRING→stringBOOL→boolINT→intFLOAT→floatARR_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.
The glob was devices/inverse*/… in 3.5.0; the leading * now sits before inverse. Config files using the old literal will fail to bind on 3.5.1 — update them. The keys themselves are otherwise unchanged.
| 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/*inverse/safeties/expose_in_snapshot | bool | — | Include per-device safety flags in GET /devices/{id} snapshots. |
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. See the Navigation module page for runtime semantics of each field.
| Key | Type | Constraints | Description |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | Default bubble centre position. |
features/navigation/bubble/center_enabled | bool | — | Apply the configured center when a bubble behaviour is first activated. |
features/navigation/bubble/rotation_enabled | bool | — | Apply the workspace rotation to the navigation direction. |
features/navigation/bubble/scale_enabled | bool | — | Apply the workspace scale to the navigation velocity. |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | Drift speed (m/s) in auto_follow centre mode. |
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/navigation/bubble/stop_at_collision | bool | — | Block the bubble centre from drifting into the collision direction when a collision is active. |
features/navigation/bubble/collision_threshold | float | > 0 | External-force magnitude (N) at which a collision is detected. |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | Multiplier applied to velocity_zone_width while a collision is active. |
features/navigation/bubble/collision_exit_ratio | float | range (0,1] | Hysteresis ratio — exit collision when |ext_force| drops below collision_threshold × this. 1.0 disables hysteresis. |
features/navigation/bubble/avatar_boundary_enabled | bool | — | Clamp the avatar world position to the configured avatar_boundary SDF shape. |
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). |
session/serialization/…
Transform-output formatting — affects WebSocket and HTTP JSON payloads. These keys moved from serialization/* to session/serialization/* in 3.5.1 to reflect their per-session scope. The old paths still resolve via deprecated aliases.
| Key | Type | Constraints | Description |
|---|---|---|---|
session/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. |
session/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 session/serialization/explicit_fields. Default: false. |
serialization/explicit_fields (deprecated) | bool | — | Use session/serialization/explicit_fields instead. Reads and writes are transparently forwarded to the canonical key. |
serialization/force_complete_transforms (deprecated) | bool | — | Use session/serialization/force_complete_transforms instead. Reads and writes are transparently forwarded to the canonical key. |
session/…
Session scheduler.
| Key | Type | Constraints | Description |
|---|---|---|---|
session/min_simulation_rate_hz | int | range 20–500 | Minimum acceptable device simulation rate (Hz) before a warning fires. |
rate/…
Service pacing. Introduced in 3.5.1 — the four rate/websocket/* keys below were previously under session/commands/*; the old paths still resolve via deprecated aliases.
| Key | Type | Constraints | Description |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | Zero-order-hold window — suppress probes received within this window (ms). |
rate/websocket/drop_warning_threshold | int | — | Number of dropped commands within the window before warning. |
rate/websocket/drop_warning_window_ms | int | — | Sliding window size for counting dropped commands (ms). |
rate/websocket/tick_on_empty_batch | bool | advanced | Schedule a main_loop tick even when an entire WebSocket batch was dropped. |
session/commands/zoh_window_ms (deprecated) | int | — | Use rate/websocket/zoh_window_ms instead. Reads and writes are transparently forwarded. |
session/commands/drop_warning_threshold (deprecated) | int | — | Use rate/websocket/drop_warning_threshold instead. Reads and writes are transparently forwarded. |
session/commands/drop_warning_window_ms (deprecated) | int | — | Use rate/websocket/drop_warning_window_ms instead. Reads and writes are transparently forwarded. |
session/commands/tick_on_empty_batch (deprecated) | bool | — | Use rate/websocket/tick_on_empty_batch instead. Reads and writes are transparently forwarded. |
Internal-only settings
Several settings families ship hidden in 3.5.1 and are reserved for internal use — rate/dispatch/* (AIMD dispatch-rate cap and back-pressure thresholds), session/freeform/* (behavioural fingerprinting), and session/serialization/preview/* (pre-release serialization experiments such as Euler quaternion output and Wireless VerseGrip routing). They are reachable through misc/hidden_settings for debugging, but expect them to be promoted, renamed, or removed in a later minor — do not pin client behaviour to them.