원격 설정 · 안전 경계Remote settings & safety

원격으로 쓸 수 있는 키는 아래 허용 목록 7종뿐이에요. 이 목록은 머신 로컬 웹의 운영자 제어가 이미 쓰는 목록과 같고, 쓰기는 CAN 쓰기 → 보드 리드백 → 확정값 응답 순서로 처리돼요.

원격으로 바꿀 수 있는 설정

읽기 · 쓰기

GET /v1/public/machines/{serial}/settings
→ 200 { "values": { "ambient_brightness": 60, … }, "epoch": 58525 }

PATCH /v1/public/machines/{serial}/settings
Authorization: Bearer <oauth2 token with settings:write:lighting>
Content-Type: application/json
{ "ambient_brightness": 50, "expected_epoch": 58525 }

→ 200 { "ok": true, "values": { "ambient_brightness": 50 }, "epoch": 58525, "read_back": true }
→ 400 { "error": "out_of_range", "key": "ambient_brightness", "range": [0, 100] }
→ 403 { "error": "not_whitelisted", "key": "boiler_setpoint_c" }
→ 409 { "error": "epoch_mismatch", "epoch": 58530 }
→ 503 { "error": "machine_offline" }

expected_epoch 는 선택이지만 권장해요. 머신 화면에서 누군가 같은 설정을 바꿨다면 409 가 돌아오고, 다시 읽은 뒤 결정하면 돼요. 응답의 values 는 보드가 다시 읽어 보고한 값이라 "썼다고 가정"하지 않아요.

안전 경계 — 앞으로도 열지 않아요

Only the seven allow-listed keys below can be written remotely — the same list the machine's local operator control already uses. A write is CAN write → board read-back → confirmed value.

PATCH /v1/public/machines/{serial}/settings
{ "ambient_brightness": 50, "expected_epoch": 58525 }
→ 200 { "ok": true, "values": { "ambient_brightness": 50 }, "read_back": true }
→ 400 out_of_range · 403 not_whitelisted · 409 epoch_mismatch · 503 machine_offline

The boundary — never opened