These endpoints change settings in firmware 3.10.4. Use URL-encoded form bodies with X-Tyson-Request: 1 and Accept: application/json. They are not JSON PATCH endpoints; a missing field can have a different effect from a field explicitly set to its current value.
Most successful settings saves return a full state object when Accept contains application/json; otherwise they return 303 See Other to /settings. A persistence failure can return 500 after the value already changed in RAM. See Errors and compatibility.
| Field | Values | Omission behavior |
|---|---|---|
max_temp_mode |
Integer 0, 1, 2: maximum 60, 90, 108°C respectively |
Required; missing/invalid gives 400. |
persist_setpoint |
1 to remember chamber target; use 0 for off |
Omitted means false. Changing from true to false also sets the current chamber target to zero. |
fan_speed |
40 Quiet, 55 Normal, 70 Fast, 85 Turbo |
Omitted preserves the current mode. Other values give 400. |
remember_fan |
0 or 1 |
Omitted preserves the current setting. |
temperature_source |
standalone or lan_only |
Omitted preserves the current source. |
Always include the intended max_temp_mode and persist_setpoint, even when changing only the fan mode. Lowering the maximum mode clamps the current chamber setpoint. A temperature-source change is accepted immediately, but temperature validity and control wait for a fresh reading from the new source. This endpoint does not set a new chamber temperature target; use WebSocket set_setpoint.
The public-facing fan labels should be Quiet, Normal, Fast and Turbo. The underlying form values are percentages; the dashboard exposes those percentages only in Debugging Mode.
Required fields:
| Field | Values |
|---|---|
channel |
hotend, right, or bed |
enabled |
0 or 1 |
right is accepted only for a recognized X2D. This switch declares installed/enabled hardware and affects control availability; it does not perform calibration or enable temperature mapping by itself. Turning a channel off stops its control while keeping calibration. It is separate from the enable action on /api/scaler or /api/bed.
| Field | Values |
|---|---|
channel |
hotend, right, or bed |
hz |
50 or 60 |
Both fields are required. The selected sensor must be enabled; calibration or bed tuning can block changes. This selects the RTD mains-rejection filter. It does not change the actual supply voltage or PWM frequency.
All fields are required:
| Field | Accepted values |
|---|---|
supply_voltage |
120, 220, 230, 240, 250 |
bed_max_power |
Whole-number percentage, 5–100 |
chamber_max_power |
Whole-number percentage, 5–100 |
bed_pwm_hz |
Whole-number frequency, 2–50 Hz |
chamber_pwm_hz |
Whole-number frequency, 2–50 Hz |
acknowledge |
Must be 1 |
These values limit the SSR control input. They are not measurements of mains voltage or actual heater wattage. Use the installed kit's specified settings and reproduce the dashboard's electrical acknowledgement in your application before sending the command.
Saving valid heater-power settings sets the chamber target to zero. It preserves the bed's enable/target/control selections while reconfiguring PWM. Bed tuning or power-output faults can block the request. If PWM configuration fails, outputs are disabled until restart and the request returns 409.
The API does not fill in power percentages just because supply_voltage is present. The dashboard fills recommended defaults before submitting all fields. The current defaults are:
| Voltage | Bed percentage | Chamber percentage |
|---|---|---|
| 120 | 85 | 100 |
| 220 | 29 | 36 |
| 230 | 27 | 33 |
| 240 | 25 | 30 |
| 250 | 23 | 28 |
Both default PWM frequencies are 10 Hz. Changing power conditions may require new PID tuning; see Calibration and backups.
| Endpoint | Fields and behavior |
|---|---|
POST /wifi/scan |
Requests a scan unless one is already running. No form fields required. |
GET /api/wifi/scan |
Reads current asynchronous scan status/results; it does not start a scan. See State and discovery. |
POST /wifi/save |
ssid or nonempty custom_ssid, plus password. A nonempty custom value takes priority over ssid. |
POST /wifi/reset |
Clears saved SSID/password. No form fields required. |
SSID length is 1–32 bytes. Password may be empty for an open network, 8–63 bytes, or 64 hexadecimal characters. An omitted password is treated as empty, not “keep the saved password.” Saving or clearing Wi-Fi can disconnect your client and change the HAT's address; rediscover it rather than replaying the request blindly.
| Field | Meaning |
|---|---|
mqtt_server |
Printer host/IP for manual mode. Required in manual mode; automatic mode uses the matching discovered printer's address. |
mqtt_port |
Required integer 1–65535; usual Bambu value is 8883. |
device_serial |
Required printer serial, at most 64 bytes, without MQTT wildcard/path characters or whitespace. |
mqtt_user |
Username, at most 128 bytes; usual Bambu value is bblp. An omitted value becomes empty. |
mqtt_pass |
LAN access code, at most 128 bytes. Empty preserves the saved code for the same printer unless clear is requested. |
clear_mqtt_password |
1 clears the saved code, including a code supplied in this request. |
printer_auto |
1 selects automatic discovery; omitted or another value selects manual mode. |
printer_developer |
1 records your confirmation that Developer Mode is enabled on the printer. Omitted means false. |
Do not implement this as a partial credentials update. Send the complete intended host/port/serial/user and boolean choices. Selecting a different serial first clears the old printer's saved code. Automatic selection normally requires a currently discovered printer; the same previously selected automatic printer can remain selected while offline. A new automatic selection, or one with no saved code, requires the selected printer's LAN access code.
The Developer Mode field is a confirmation only; the HAT does not enable that setting on the printer. Saving connection settings invalidates the previous MQTT connection and can stop or rebind calibration/mapping work. Coordinate connection changes with the user.
POST /mqtt/test requests reconnect using the saved connection configuration. It takes no form fields and returns state with Accept: application/json; it is not a synchronous end-to-end connection test. Check later mqtt_connected and connection-status fields.
This is a destructive configuration operation. It erases saved Wi-Fi/printer settings and custom calibration and restarts the HAT. It does not install a different firmware version. Require an explicit user action in your integration rather than invoking it as automatic error recovery.
Required fields are confirm=factory-reset and boot equal to the latest boot_id from /api/state. An invalid confirmation or boot ID returns 400. A successful request responds with:
{"accepted":true}
The reset is scheduled after the response. Plan to lose the connection and use the setup network afterwards. See the user guide for the distinction between resetting a single network setting and a factory reset.