set_config Configurable Field Reference (Navigation Service / Camera Services / Motion Planning Service / Control Service)
GalbotRobot.set_config() modifies the runtime configuration of the navigation service, camera services, motion planning service, and control service. This document lists every field currently supported by these services, along with its meaning, type, and valid range. For the signature, parameters, and return value of the interface itself, see the description of GalbotRobot.set_config in the Python API Reference / C++ API Reference.
A few key behaviors to understand before using this API:
Use key names exactly as listed in the tables below.
The call returns only a single aggregate ControlStatus; it does not tell you which specific field caused a failure. When a call does not succeed, check the ERR lines in the SDK log (under ~/galbot_sdk_log/g3/) to find the reason.
A single call can set multiple fields at once. If any field is invalid (not in the tables below, or its value is out of range), the entire batch is rejected and none of it takes effect.
Important
A successful set_config() call (returning ControlStatus.SUCCESS) only means the configuration has been saved -- it does not take effect immediately. Please restart the device after configuration; the new settings will only be loaded and applied by the relevant service after a restart.
ESDF map path; if the map does not exist, the service enters an error state
forbidden_dyn_map
bool
-
Whether to disable the dynamic map (turns dynamic obstacle avoidance on/off)
use_static_map
bool
-
Enable static-map planning: path search runs on the static map, the dynamic map is only used for real-time collision checking; when blocked by an obstacle the robot stops instead of going around it
evaluate_at_dyn_map
bool
-
Whether to perform reachability estimation on the dynamic map layer (when enabled, reachability is also evaluated on the dynamic layer; when disabled, only the static layer is used)
Whether to immediately report failure (without attempting to replan) when planning fails or a collision is detected during execution
task_timeout_sec
float
seconds
Global timeout for a single navigation request; if not completed within this time, the request is reported as failed. A positive value is the timeout duration; a non-positive value means no timeout (unlimited replanning is allowed)
dyn_plan
bool
-
Whether to enable continuous dynamic replanning (Beta): when enabled, no stop command is issued during replanning -- the last executed trajectory position is used as the starting condition so obstacle-avoidance motion stays continuous; when disabled (default), the base stops before replanning
replan_threshold
float
> 0.1, in m
Replanning is skipped once the current position is closer than this threshold to the starting point; replan_threshold + no_replan_threshold must be less than planning_horizen, otherwise active replanning stops working
no_replan_threshold
float
> 0.1, in m, typically 1.0
Replanning is skipped once the current position is closer than this threshold to the goal; too small a value can cause trajectory jitter from replanning near the goal
planning_horizen
float
> 0, in m
Local planning horizon; only the path within this range is planned each time. Anything beyond it is truncated to this length and completed over multiple replanning segments
search_closest_distance
float
> 0, in m
Distance kept from obstacles for the partial path returned when path search fails; if larger than half the width of a feasible corridor, that area is treated as unreachable
Left-arm end-effector tool type, used to include the end-effector in environment collision checking during navigation planning: 0=None, 1=gripper_hitbot, 2=suction_cup, 3=robotiq_gripper, 4=galbot_gripper, 5=GE103, 6=GE103v1 (default 0, collision not considered)
right_arm
int
enum 0~6
Right-arm end-effector tool type, same meaning as left_arm
Distance kept between path points and obstacles (hard constraint)
search_start_radius
float
> 0, in m
Specialized radius around the start point, during path search
search_end_radius
float
> 0, in m
Specialized radius around the goal point, during path search
start_safe_margin
float
> 0, in m
Distance to obstacles within the start-point specialized radius, for cases where the starting point is close to an obstacle
end_safe_margin
float
> 0, in m
Distance to obstacles within the goal-point specialized radius, for cases where the goal is close to an obstacle
return_closest_path
bool
-
Whether to return the feasible partial path closest to the goal when path search fails (path blocked); use with caution when the goal is behind a shelf/wall, as it can look like the robot went to the wrong place
Distance kept between path control points and obstacles (soft constraint); should be greater than the search-phase safety distance, typically by 0.2~0.5m
start_safe_distance
float
> 0, in m
Distance to obstacles within the start-point specialized radius
end_safe_distance
float
> 0, in m
Distance to obstacles within the goal-point specialized radius
optimize_start_radius
float
> 0, in m
Specialized radius around the start point, during trajectory optimization
optimize_end_radius
float
> 0, in m
Specialized radius around the goal point, during trajectory optimization
post_check_hard_safe_distance
float
> 0, in m
Post-optimization hard constraint: planning is judged to have failed if the final planned path's distance to an obstacle is below this value
weight_obstacle
float
> 0
Obstacle-distance weight (safety weight); by default safety is prioritized, and a larger value further prioritizes obstacle avoidance
weight_smooth
float
larger = smoother; 20.0~50.0 usually works well
Trajectory smoothness weight; can be increased in open scenes that don't require hugging obstacles closely, to improve navigation smoothness
Distance ahead of the robot's current position, along the planned path, over which collisions are predicted during navigation execution; too large a value can cause frequent replanning or jerky/stuttering motion
collision_check_plan_path
bool
-
Whether to check the full trajectory (cylindrical envelope) for collision feasibility once planning completes, and withhold execution if infeasible; can be disabled in high dynamic-response or mapless long-range navigation scenarios in favor of runtime collision prediction + dynamic replanning
length 3, in m/s and rad/s, element range (0, 1.5)
Maximum navigation planning velocity [vx, vy, w]; the robot's control-side velocity limit must be kept no lower than this value, otherwise the robot may fail to track the planned velocity
max_acceleration
List[float]
length 3
Maximum navigation planning acceleration [ax, ay, aw]; normally left unchanged
max_jerk
List[float]
length 3
Maximum navigation planning jerk [jx, jy, jw]; normally left unchanged
enable_centripetal_constraint
bool
-
Whether to enable the centripetal acceleration constraint
max_centripetal_acc
float
> 0
Upper bound for the centripetal acceleration constraint
control_cycle_time
float
normally left unchanged
Time interval between planned waypoints (control cycle), determining how densely waypoints are packed
Arrival position error (X direction); the robot's control accuracy must be smaller than this arrival error, otherwise the robot may fail to reach the target; control accuracy should not be smaller than 1cm
Whether to enable omnidirectional planning (simultaneous translation and rotation); when disabled, standard heading-based navigation (turn first, then move straight) is used. Due to limited lidar field of view, moving omnidirectionally with an obstacle behind the robot carries a collision risk -- enable based on the scene. On S1 this returns INVALID_INPUT
stop_err
float
in m (G-series default 0.2, S1 default 0.5)
Short-distance-move threshold: once the distance between the current position and target is below this value, the short-distance motion mode is used
Whether to first attempt a straight-line omnidirectional move (rotate + crab-walk on S1) to the goal, executing it if collision-free, otherwise falling back to regular planning
try_omni_plan_min_obstacle_distance
float
> 0, in m
Distance kept from obstacles for the straight-line omnidirectional waypoints attempted above
in m; ≥0 enables it (recommended 0.2), <0 disables it
Distance kept between the start/end positions and obstacles (the robot's or a specified link's cylindrical envelope surface) during planning; should be set together with find_valid_pos_step
find_valid_pos_step
float
in m; ≥0 enables it (recommended 0.05), <0 disables it
Step size for searching the best safe distance when the requested start/end obstacle clearance can't be achieved (narrow corridors); should be set together with dis_with_obstacle
find_start_valid_pos_check_link_list
List[str]
from the URDF
Link list included in envelope checking when searching for a clearance point near the start
find_end_valid_pos_check_link_list
List[str]
from the URDF
Link list included in envelope checking when searching for a clearance point near the goal; a smaller link list avoids inserting redundant transition points caused by an oversized cylindrical envelope when the upper body's arm span is large
Whether to enable recovery adjustment (entering a recovery strategy when the planned path collides); when enabled, if static-map planning is also enabled, the stop-on-obstacle behavior stops working
recovery_strategy_order
List[int]
element enum 0~3, recommended order [1,2,3,0]
Order in which recovery strategies are attempted: 0=navigate to a designated transition point, 1=go straight omnidirectionally (rotate + crab-walk on S1), 2=search for an in-place rotation point based on the collision location, 3=handle by collision-location category
adjust_motion_types
List[int]
element enum 0~2
Motion modes attempted, in configured order, to reach a transition point away from the obstacle: 0=omnidirectional (G-series), 1=crab-walk + rotate, 2=rotate + crab-walk
transition_poses
List[List[float]]
each item length 3 or 7
List of designated recovery transition-point poses, each [x,y,yaw] or [x,y,z,rx,ry,rz,rw]; when multiple are set, the fastest feasible one is chosen
Whether to save each navigation run's process data (dynamic map, local map at time of collision, planned path), for reproducing issues and visual debugging
Camera configuration is split into 4 independent ConfigService values:
ConfigService
Supported Platforms
LEFT_ARM_CAMERA
G-series / S1
RIGHT_ARM_CAMERA
G-series / S1
FRONT_HEAD_CAMERA
G-series / S1
SURROUND_CAMERAS
G-series only; calling on S1 returns INVALID_INPUT
Only the fields listed below can be set; any other field is out of scope and passing it causes the whole batch to be rejected.
Resolution width/height must be set as a pair
color_width/color_height (present on all 4 camera services) and rs_color_width/rs_color_height (LEFT_ARM_CAMERA/RIGHT_ARM_CAMERA only, RealSense-specific) must be included together in the same set_config() call, and their combined values must be one of the valid combinations listed in the Range column below. Passing only one of the two, or passing both with an invalid combination, causes the whole batch to be rejected. Even if you only want to change one of them, you must resend the other's target value as well.
LEFT_ARM_CAMERA / RIGHT_ARM_CAMERA (identical field definitions on both services)
G3 uses monocular arm cameras and does not provide arm-mounted depth cameras. color_width/color_height controls the final-output resolution. The RealSense-specific fields remain in the shared configuration schema for G1/S1 compatibility and do not enable depth-camera support on G3.
Field (key)
Type
Range
Description
color_width
int
paired with color_height; valid combinations: (1920,1536)(1280,1024)
Final-output image width
color_height
int
see above
Final-output image height
frame_rate
int
enum 30, 15
Final-output frame rate
rs_color_width
int
paired with rs_color_height; valid combinations: (1280,720)(848,480)(640,480)(640,360)(480,270)(424,240)
RealSense capture image width
rs_color_height
int
see above
RealSense capture image height
rs_frame_rate
int
enum 30, 15, 9, 6
RealSense camera frame rate; RealSense only supports these 4 values
ir_enabled
bool
-
Whether to enable infrared image publishing
imu_enabled
bool
-
Whether to enable IMU data publishing; currently only supported on D436
iframe_interval
int
≥ 2
I-frame interval; recommended to be a multiple of the frame rate
from galbot_sdk.g3 import GalbotRobot, ConfigService, ConfigItem, ControlStatus robot = GalbotRobot() robot.init() # Front head camera: set resolution (width/height must be sent together) status = robot.set_config( ConfigService.FRONT_HEAD_CAMERA, [ ConfigItem("color_width",1280), ConfigItem("color_height",992), ], ) print(status) robot.request_shutdown() robot.wait_for_shutdown() robot.destroy()
Motion Planning Service (ConfigService.MOTION_PLAN)
The fields supported by the motion planning service are listed below, grouped by function. Available on both G-series and S1.
Some fields must be configured per body chain. The chain name can be one of 5 values: head, left_arm, right_arm, torso (waist), leg (lower body/lift). These fields follow the key naming pattern {field_name}_{chain_name}, e.g. max_velocity_left_arm.
The array length (number of joints) for each chain differs by platform:
Chain
G-series
S1
head
2
2
left_arm
7
7
right_arm
7
7
torso
2
1
leg
5
1
The array length must exactly match the joint count of the corresponding chain on the currently connected platform, otherwise the field is rejected.
ik_soft_limit_lower_{chain} and ik_soft_limit_upper_{chain} must be included together in the same set_config() call; passing only one causes the whole batch to be rejected.
sample_planner_limit_lower_{chain} and sample_planner_limit_upper_{chain} must be included together in the same set_config() call; passing only one causes the whole batch to be rejected.
The control service's fields are spread across several chassis/body controllers. The same field name (e.g. max_vel, stop_acc, pos_threshold) appears in more than one controller, so friendly keys are disambiguated with a {field_name}_{controller_suffix} pattern, e.g. max_vel_chassis_pose, max_vel_chassis_pose_fast. Whether a given controller is available on the currently connected robot is determined at runtime (e.g. the high-speed-tuned chassis controller only exists on some models); the field is rejected when it isn't applicable.
Each table below has a "Platform" column right next to the field key so you don't have to cross-reference the section heading.
The set and order of groups that participate in initialization; a structural field -- changing it incorrectly may stop some subsystems from initializing, so edit with care
report_error_skip
G-series / S1
int
≥ 1
How many main-loop cycles between each error report
report_sensor_skip
G-series / S1
int
≥ 1
How many main-loop cycles between each sensor report
report_wbc_info_skip
G-series / S1
int
≥ 1
How many main-loop cycles between each wbc_info report
report_wbcs_info_skip
G-series / S1
int
≥ 1
How many main-loop cycles between each wbcs_info report
report_fault_skip
G-series / S1
int
≥ 1
How many main-loop cycles between each fault heartbeat report
target_sub_log_skip
G-series / S1
int
≥ 1
How many target-processing cycles between each received-target log line; log output only
target_sampling_default
G-series / S1
str
enum LinearInterpolate, DirectPass
Default sampling/interpolation strategy for the control target within a control cycle, when not otherwise specified
wbc_rate
G-series / S1
float
> 0, in Hz
Target frequency of the control main loop; restart the device after changing this and verify the actual effective frequency
must be one of the controller names currently registered for {group} (validated at runtime, not a fixed enum); {group} itself must also be a group that genuinely exists on the robot, otherwise it's rejected
Switches the currently-active controller for group {group}. For example, group_controller_default_chassis set to "chassis_pose_ctrl_fast" switches the chassis to the high-speed-tuned controller (provided that controller is already registered in the system). Common {group} values include chassis, head, left_arm, right_arm, etc.
The valid range is read live, not a fixed table
The valid values for group_controller_default_{group} depend on which controllers are currently registered on the robot, and can vary by model and by scene -- it isn't a fixed field table. Passing a group name that doesn't exist, or a controller name that isn't registered for that group, is rejected.
Range comes from the device's currently configured height bounds (read live, not a fixed constant; the typical factory range is approximately [1.14, 1.72] meters)
from galbot_sdk.g3 import GalbotRobot, ConfigService, ConfigItem, ControlStatus robot = GalbotRobot() robot.init() # report_error_skip is a general parameter shared by both G-series and S1 status = robot.set_config( ConfigService.CONTROL, [ ConfigItem("report_error_skip",1), ], ) print(status) robot.request_shutdown() robot.wait_for_shutdown() robot.destroy()