---
title: "Update reel settings"
method: PUT
path: "/api/v1/reel/settings"
tags: ["v1", "settings"]
---

# Update reel settings

`PUT /api/v1/reel/settings`

Modify operational configuration parameters for the reel system including 
safety controls, cable limits, and advanced features.

Allows selective updates to reel configuration by providing only the settings 
to be modified (null values are ignored). Changes are validated for consistency 
and safety before being applied to the system. Safeguard synchronization ensures 
master safeguard control properly reflects individual safeguard states.

Critical safety settings modifications require careful consideration as they 
directly affect operational limits and protection mechanisms. Changes are 
immediately applied and saved to persistent configuration storage.

## Request body

- UpdateReelSettingsRequest — Request data for updating reel system configuration.
  - `reel_safeguards_enabled` boolean, nullable — Master control for all reel safety systems. When True, enables safety monitoring and protection features. When False, disables all safeguards for maintenance or emergency operations. Changes automatically sync with individual safeguard settings.
  - `safeguards` SafeguardSettings — Individual safeguard control settings for granular safety management.
    - `no_cable_movement_enabled` boolean — Detection and alerting for cable movement failures. When enabled, monitors for situations where cable should be moving based on motor commands but encoder readings indicate no movement. Helps detect mechanical failures or obstructions.
    - `zero_point_enabled` boolean — Protection against cable over-retraction past zero point. Prevents cable from winding past the established zero point plus gutter distance. Essential for preventing cable damage and maintaining proper reference positioning.
    - `max_tether_length_enabled` boolean — Protection against cable over-extension beyond maximum length. Prevents unwinding beyond the configured maximum cable length to protect against cable damage, spool depletion, or operational area violations.
    - `motor_safe_deceleration_enabled` boolean — Automatic motor deceleration when approaching safety limits. When enabled, gradually reduces motor speed when approaching zero point or maximum tether length limits, or when approaching go-to targets.
  - `max_cable_length_meters` number, nullable — Maximum allowed cable extension distance in meters. Defines the operational limit for cable unwinding to prevent over-extension, cable damage, or operational area violations. Must be positive value greater than zero.
  - `zero_point_gutter` number, nullable — Safety margin distance from zero point in meters. Additional retraction distance beyond the established zero point where the system will stop winding. Prevents over-retraction and provides operational safety margin.
  - `always_enable_remote_control` boolean, nullable — Remote control override for physical controls. When True, prevents physical control interfaces from disabling remote API control. When False, allows physical controls to disable remote operations for safety.
  - `active_position_hold_enabled` boolean, nullable — Active motor position holding feature control. Enables/disables the system's ability to actively maintain the last stopped position using motor encoder feedback and PID control. Requires motor position encoder installation.
  - `motoron_speed_boost` MotoronSpeedBoostSettings — Motor speed boost configuration for enhanced performance.
    - `enabled` boolean — Speed boost feature activation status. When enabled, allows motor to exceed standard speed limits during specific operations for improved performance. Only available with compatible Motoron motor drivers.
    - `speed_boost_percentage` integer — Speed boost multiplication factor as percentage. Defines the maximum speed increase when boost is active. 150% provides 50% speed increase, 200% doubles the speed. Higher values provide faster operation but may affect precision.
  - `motor_deceleration` object, nullable — Motor deceleration configuration for API requests and responses.
    - `trigger_distance_meters` number, required — Distance from safety limit where deceleration begins in meters. Controls when the motor starts reducing speed as it approaches safety boundaries. Larger values provide more gradual deceleration but start slowing down earlier.
    - `decelerated_speed_percent` integer, required — Target speed percentage during deceleration phase. Motor speed when approaching safety limits. Lower values provide more conservative approach but may extend operation time. Must be greater than minimum speed.
    - `minimum_speed_percent` integer, required — Absolute minimum speed percentage (safety floor). Lowest speed the motor will operate at during deceleration. Ensures motor maintains enough torque for control while providing maximum safety margin.
    - `minimum_trigger_distance` number, required — Minimum trigger distance to prevent false triggers in meters. Safety threshold to prevent deceleration activation from minor position fluctuations or encoder noise. Should be smaller than trigger distance.
  - `zero_point_reset` boolean, nullable — Cable counter position reset configuration. If `zero_point_reset` is true, when the reed switch is closed (active) the reel will reset the cable counter position to 0. This is to accommodate cable counter drift or slippage during operation and set the position back to a known quantity.
  - `bypasses` object, nullable — Individual bypass control settings for operational flexibility.
    - `reed_switch_bypassed` boolean — Bypass reed switch position reset functionality. When enabled, ignores reed switch activation.
  - `reed_switch` object, nullable — Reed switch configuration for update requests.
    - `role` 'emergency_stop' | 'limit_hold' | 'benson_push_push_lock', required

## Response `200`

Successful Response

- UpdateReelSettingsResponse — Response for reel settings update operations. Confirms successful application of configuration changes and returns the updated system settings. Includes validation results and current configuration state.
  - `action` string, required — The action that was requested or performed by the endpoint
  - `error` boolean, required — Indicates whether the operation encountered an error
  - `error_msgs` string[] — List of error messages if the operation failed
  - `result` UpdateReelSettingsResult, required — Result container for reel settings update operations.
    - `settings` ReelSettings, required
      - `loop_control_mode` 0 | 1, required
      - `reel_safeguards_enabled` boolean
      - `safeguards` SafeguardSettings — Individual safeguard control settings for granular safety management.
        - `no_cable_movement_enabled` boolean — Detection and alerting for cable movement failures. When enabled, monitors for situations where cable should be moving based on motor commands but encoder readings indicate no movement. Helps detect mechanical failures or obstructions.
        - `zero_point_enabled` boolean — Protection against cable over-retraction past zero point. Prevents cable from winding past the established zero point plus gutter distance. Essential for preventing cable damage and maintaining proper reference positioning.
        - `max_tether_length_enabled` boolean — Protection against cable over-extension beyond maximum length. Prevents unwinding beyond the configured maximum cable length to protect against cable damage, spool depletion, or operational area violations.
        - `motor_safe_deceleration_enabled` boolean — Automatic motor deceleration when approaching safety limits. When enabled, gradually reduces motor speed when approaching zero point or maximum tether length limits, or when approaching go-to targets.
      - `max_cable_length_meters` number, required
      - `zero_point_gutter` number, required
      - `always_enable_remote_control` boolean, required
      - `active_position_hold_enabled` boolean, required
      - `motoron_speed_boost` MotoronSpeedBoostSettings, required — Motor speed boost configuration for enhanced performance.
        - `enabled` boolean — Speed boost feature activation status. When enabled, allows motor to exceed standard speed limits during specific operations for improved performance. Only available with compatible Motoron motor drivers.
        - `speed_boost_percentage` integer — Speed boost multiplication factor as percentage. Defines the maximum speed increase when boost is active. 150% provides 50% speed increase, 200% doubles the speed. Higher values provide faster operation but may affect precision.
      - `motor_deceleration` MotorDecelerationSettings — Motor deceleration configuration for API requests and responses.
        - `trigger_distance_meters` number, required — Distance from safety limit where deceleration begins in meters. Controls when the motor starts reducing speed as it approaches safety boundaries. Larger values provide more gradual deceleration but start slowing down earlier.
        - `decelerated_speed_percent` integer, required — Target speed percentage during deceleration phase. Motor speed when approaching safety limits. Lower values provide more conservative approach but may extend operation time. Must be greater than minimum speed.
        - `minimum_speed_percent` integer, required — Absolute minimum speed percentage (safety floor). Lowest speed the motor will operate at during deceleration. Ensures motor maintains enough torque for control while providing maximum safety margin.
        - `minimum_trigger_distance` number, required — Minimum trigger distance to prevent false triggers in meters. Safety threshold to prevent deceleration activation from minor position fluctuations or encoder noise. Should be smaller than trigger distance.
      - `zero_point_reset` boolean, required
      - `bypasses` BypassSettings — Individual bypass control settings for operational flexibility.
        - `reed_switch_bypassed` boolean — Bypass reed switch position reset functionality. When enabled, ignores reed switch activation.

## Other responses

- `401` — Could not validate credentials
- `403` — Setup required before using this endpoint
- `422` — Validation Error
- `500` — Internal server error

---

[API](https://skmtc.net/reach-systems-tech/apis/reelapi-v1.md) · [All operations](https://skmtc.net/reach-systems-tech/apis/reelapi-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/reach-systems-tech/reelapi-v1/revisions/1dd366a9c6a3/schema)