This guide targets the Bambu-connected firmware 3.10.4. Find the HAT's address with the Discovery app, its .local hostname, or your network's device list. All examples below use 192.0.2.42 as a placeholder.
New HATs start with dashboard admin / admin and developer access off. Sign in at the HAT, open Settings > Network > Developer API Access, select Enable API Access Code, and save the generated code. Replace AB23CD45 below with that code. It is separate from the dashboard password and the printer's LAN code. A valid dashboard browser session is an alternative; omitting all authentication works only after Disable All Security has been saved. See Dashboard login and API access.
curl --max-time 10 \
-H 'Accept: application/json' \
-H 'X-Tyson-Access-Code: AB23CD45' \
http://192.0.2.42/api/state
In Windows PowerShell, use curl.exe for curl commands and put the command on one line, or use PowerShell's backtick continuation instead of the shell backslash shown here.
Check hardware_serial to identify the HAT, firmware_version for compatibility, and boot_id for restarts. Read the relevant installed/enabled/calibrated/fault fields before offering a control in your program. A null temperature is an unavailable reading, not zero. See State and discovery.
Ordinary POST handlers expect application/x-www-form-urlencoded, not a JSON object. Send:
Accept: application/json
Content-Type: application/x-www-form-urlencoded
X-Tyson-Request: 1
Accept matters: settings handlers can otherwise respond with a browser redirect to /settings. Ordinary form bodies are limited to 2048 bytes. Calibration upload and firmware upload have different bodies and limits; follow their transfer reference.
For example, selecting the 300→400°C hotend preset uses:
curl --max-time 10 \
-H 'Accept: application/json' \
-H 'X-Tyson-Access-Code: AB23CD45' \
-H 'X-Tyson-Request: 1' \
--data 'action=settings&maximum=400' \
http://192.0.2.42/api/scaler
This command changes configuration. It does not enable mapping and is not a request to heat to 400°C. Use only a preset appropriate to the installed hardware. Successful scaler actions return 202 Accepted with state; observe pending/save fields and read state again before concluding that an asynchronous operation has finished.
An X2D right-hotend request adds hotend=right. The field is hotend for scaler actions; calibration file transfers instead use the X-Tyson-Hotend header. See the corresponding references for each operation.
Connect to ws://192.0.2.42:81/ with Origin: http://192.0.2.42 and X-Tyson-Access-Code: YOUR_CODE in the native client's upgrade headers, then send:
{"id":1,"method":"set_setpoint","value":55}
Match the reply's ack_id to 1 and inspect its actual chamber_setpoint. A value of 0 requests chamber heating off. The firmware clamps an otherwise valid target to the saved chamber maximum. Browser connections can supply only their page's own Origin automatically; a script served from the wiki cannot impersonate the HAT's origin. Use an appropriate native client or a script running in the HAT dashboard's origin. See WebSocket API for complete framing and error handling.
Download the Python HTTP example and tests, or use examples/python/tyson_client.py from the full wiki source bundle. It uses Python 3.10+ and the standard library; no pip packages are required. It supports state, hotend presets and mapping, bed presets/control, and fan commands. It does not implement WebSocket or firmware uploads.
Read state without changing a setting:
python wiki/examples/python/tyson_client.py --host http://192.0.2.42 --ask-access-code
An explicit preset-selection command, when appropriate for the installed hardware:
python wiki/examples/python/tyson_client.py --host http://192.0.2.42 --ask-access-code hotend-settings 400 --hotend left
The prompt hides your code and avoids placing it in shell history. The curl values above are demonstration placeholders; prefer the hidden prompt for interactive use. See the adjacent examples/python/README.md and run the script with --help for its exact command syntax. Its default operation reads state. Write operations are explicit subcommands, use finite timeouts and never automatically retry. The result retains the HTTP status so callers can distinguish 202 Accepted from a completed operation. A mock-server test suite accompanies it.
boot_id and state sequence before a command.boot_id changes, discard old sequence comparisons and pending command assumptions. Read a fresh state; do not automatically replay heater or calibration commands.The HAT has limited simultaneous HTTP/WebSocket connections. Reuse one WebSocket for live telemetry or poll conservatively with timeouts and backoff. Avoid opening a new connection for every visible value. Operational constraints and failures are documented in Errors and compatibility.