feat: add spindle direction selection contract

This commit is contained in:
Nick Hermes
2026-06-02 15:40:16 +00:00
parent 02d9323c43
commit beeb521ca7
21 changed files with 689 additions and 133 deletions

View File

@@ -65,13 +65,23 @@
"description": "Explicit record of every constraint, clip, or approximation applied.",
"items": {
"type": "object",
"required": ["source_pass_id", "field", "description"],
"required": [
"source_pass_id",
"field",
"description"
],
"properties": {
"source_pass_id": { "type": "string" },
"field": { "type": "string" },
"source_pass_id": {
"type": "string"
},
"field": {
"type": "string"
},
"planned_value": {},
"translated_value": {},
"description": { "type": "string" }
"description": {
"type": "string"
}
}
}
}
@@ -86,31 +96,71 @@
"duration_s",
"commanded_force_n",
"commanded_table_rpm",
"commanded_spindle_rpm"
"commanded_spindle_rpm",
"commanded_spindle_direction"
],
"properties": {
"segment_id": { "type": "string" },
"sequence_index": { "type": "integer", "minimum": 1 },
"segment_id": {
"type": "string"
},
"sequence_index": {
"type": "integer",
"minimum": 1
},
"source_pass_id": {
"type": "string",
"description": "Back-reference to the planning pass this segment came from."
},
"duration_s": { "type": "number", "minimum": 0 },
"commanded_force_n": { "type": "number", "minimum": 0 },
"commanded_table_rpm": { "type": "number", "minimum": 0 },
"commanded_spindle_rpm": { "type": "number", "minimum": 0 },
"commanded_cam_amplitude_deg": { "type": "number" },
"commanded_cam_offset_deg": { "type": "number" },
"duration_s": {
"type": "number",
"minimum": 0
},
"commanded_force_n": {
"type": "number",
"minimum": 0
},
"commanded_table_rpm": {
"type": "number",
"minimum": 0
},
"commanded_spindle_rpm": {
"type": "number",
"minimum": 0
},
"commanded_cam_amplitude_deg": {
"type": "number"
},
"commanded_cam_offset_deg": {
"type": "number"
},
"force_modulation": {
"type": "object",
"properties": {
"harmonic": { "type": "integer" },
"amplitude_n": { "type": "number" },
"phase_deg": { "type": "number" }
"harmonic": {
"type": "integer"
},
"amplitude_n": {
"type": "number"
},
"phase_deg": {
"type": "number"
}
}
},
"dither_profile": { "type": "string" },
"notes": { "type": "string" }
"dither_profile": {
"type": "string"
},
"notes": {
"type": "string"
},
"commanded_spindle_direction": {
"type": "string",
"enum": [
"cw",
"ccw"
],
"description": "Toolhead spindle rotation direction, as viewed from above the toolhead looking down toward the mirror/tool contact. ODrive sign mapping is commissioned to match this physical convention."
}
}
}
}

View File

@@ -25,7 +25,8 @@
"phase_deg": 37.2
},
"dither_profile": "none",
"notes": "Direct translation no segmentation needed for 1200s duration."
"notes": "Direct translation \u2014 no segmentation needed for 1200s duration.",
"commanded_spindle_direction": "cw"
}
],
"translation_losses": []

View File

@@ -36,7 +36,8 @@
"amplitude_n": 5.0,
"phase_deg": 37.2
},
"notes": "Phase derived from Zernike fit of pre-polish interferogram."
"notes": "Phase derived from Zernike fit of pre-polish interferogram.",
"spindle_direction": "cw"
}
],
"predicted_outcome": {
@@ -53,7 +54,10 @@
}
},
"uncertainty": {
"removal_rms_nm_range": [14.0, 24.0],
"removal_rms_nm_range": [
14.0,
24.0
],
"notes": "Uncertainty dominated by Preston coefficient calibration spread."
},
"attachments": [

View File

@@ -5,31 +5,85 @@
"machine_name": "Fullum Swing-Arm Polisher",
"controller_version": "polisher-control/0.1.0",
"last_verified": "2026-06-01T00:00:00Z",
"supported_motion_families": ["swing-arm-rosette"],
"force_range_n": [5, 200],
"table_rpm_range": [0.5, 10.0],
"spindle_rpm_range": [10, 120],
"cam_amplitude_range_deg": [1.0, 31.3],
"cam_offset_range_deg": [-30.0, 30.0],
"supported_motion_families": [
"swing-arm-rosette"
],
"force_range_n": [
5,
200
],
"table_rpm_range": [
0.5,
10.0
],
"spindle_rpm_range": [
10,
120
],
"cam_amplitude_range_deg": [
1.0,
31.3
],
"cam_offset_range_deg": [
-30.0,
30.0
],
"force_modulation": {
"supported": true,
"max_harmonics": 3,
"max_amplitude_n": 24.0,
"notes": "m=2 astigmatism and m=3 trefoil are proven channels. m=1 coma is unreliable (score 0.09)."
},
"supported_dither_profiles": ["none", "default"],
"supported_dither_profiles": [
"none",
"default"
],
"segment_duration_limits": {
"min_s": 30,
"max_s": 7200
},
"pause_resume_support": true,
"telemetry_channels": [
{ "name": "table_rpm", "unit": "RPM", "sample_rate_hz": 100 },
{ "name": "spindle_rpm", "unit": "RPM", "sample_rate_hz": 100 },
{ "name": "force_n", "unit": "N", "sample_rate_hz": 100 },
{ "name": "arm_angle_deg", "unit": "degrees", "sample_rate_hz": 100 },
{ "name": "table_angle_deg", "unit": "degrees", "sample_rate_hz": 100 },
{ "name": "timestamp_ms", "unit": "ms", "sample_rate_hz": 100 }
{
"name": "table_rpm",
"unit": "RPM",
"sample_rate_hz": 100
},
{
"name": "spindle_rpm",
"unit": "RPM",
"sample_rate_hz": 100
},
{
"name": "force_n",
"unit": "N",
"sample_rate_hz": 100
},
{
"name": "arm_angle_deg",
"unit": "degrees",
"sample_rate_hz": 100
},
{
"name": "table_angle_deg",
"unit": "degrees",
"sample_rate_hz": 100
},
{
"name": "timestamp_ms",
"unit": "ms",
"sample_rate_hz": 100
},
{
"name": "spindle_direction_setpoint",
"unit": "enum(cw|ccw)",
"sample_rate_hz": 10
},
{
"name": "spindle_direction_actual",
"unit": "enum(cw|ccw)",
"sample_rate_hz": 10
}
],
"safety_limits": {
"max_force_n": 200,
@@ -38,14 +92,18 @@
"notes": "Force hard-limited by load cell interlock. RPM limits are VFD/servo configured."
},
"known_constraints": [
"Cam amplitude is not servo-programmable must be set mechanically before run.",
"Cam amplitude is not servo-programmable \u2014 must be set mechanically before run.",
"Force modulation bandwidth limited to ~5 Hz by actuator response.",
"Table encoder is absolute but may have 1-2 count jitter.",
"Serial interface to Teensy limits command update rate to ~50 Hz effective."
],
"unknowns": [
"Exact force modulation phase accuracy at m=3 harmonic not yet validated on hardware.",
"Exact force modulation phase accuracy at m=3 harmonic \u2014 not yet validated on hardware.",
"Thermal drift effect on force sensor over runs longer than 1 hour.",
"Arm pivot play magnitude under varying force loads."
],
"supported_spindle_directions": [
"cw",
"ccw"
]
}

View File

@@ -20,7 +20,8 @@
"table_rpm": 4.0,
"spindle_rpm": 40.0,
"cam_amplitude_deg": 31.3,
"cam_offset_deg": 0.0
"cam_offset_deg": 0.0,
"spindle_direction": "cw"
},
"actual": {
"force_n_mean": 44.7,
@@ -37,7 +38,8 @@
"commanded_summary": {
"force_n": 45.0,
"table_rpm": 4.0,
"spindle_rpm": 40.0
"spindle_rpm": 40.0,
"spindle_direction": "cw"
},
"actual_summary": {
"force_n_mean": 44.7,

View File

@@ -55,15 +55,21 @@
},
"strategy_summary": {
"type": "object",
"required": ["intent"],
"required": [
"intent"
],
"properties": {
"intent": { "type": "string" },
"intent": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"notes": { "type": "string" }
"notes": {
"type": "string"
}
}
},
"passes": {
@@ -77,11 +83,17 @@
"type": "object",
"description": "Summary of predicted post-polish surface state.",
"properties": {
"removal_rms_nm": { "type": "number" },
"removal_pv_nm": { "type": "number" },
"removal_rms_nm": {
"type": "number"
},
"removal_pv_nm": {
"type": "number"
},
"residual_zernikes": {
"type": "object",
"additionalProperties": { "type": "number" }
"additionalProperties": {
"type": "number"
}
}
}
},
@@ -91,22 +103,35 @@
"properties": {
"removal_rms_nm_range": {
"type": "array",
"items": { "type": "number" },
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"notes": { "type": "string" }
"notes": {
"type": "string"
}
}
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"required": ["filename", "role"],
"required": [
"filename",
"role"
],
"properties": {
"filename": { "type": "string" },
"role": { "type": "string" },
"description": { "type": "string" }
"filename": {
"type": "string"
},
"role": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
@@ -121,37 +146,81 @@
"force_n",
"table_rpm",
"spindle_rpm",
"spindle_direction",
"motion_family"
],
"properties": {
"pass_id": { "type": "string" },
"sequence_index": { "type": "integer", "minimum": 1 },
"objective": { "type": "string" },
"preset_name": { "type": "string" },
"duration_s": { "type": "number", "minimum": 0 },
"force_n": { "type": "number", "minimum": 0 },
"table_rpm": { "type": "number", "minimum": 0 },
"spindle_rpm": { "type": "number", "minimum": 0 },
"motion_family": { "type": "string" },
"pass_id": {
"type": "string"
},
"sequence_index": {
"type": "integer",
"minimum": 1
},
"objective": {
"type": "string"
},
"preset_name": {
"type": "string"
},
"duration_s": {
"type": "number",
"minimum": 0
},
"force_n": {
"type": "number",
"minimum": 0
},
"table_rpm": {
"type": "number",
"minimum": 0
},
"spindle_rpm": {
"type": "number",
"minimum": 0
},
"motion_family": {
"type": "string"
},
"motion_params": {
"type": "object",
"additionalProperties": true
},
"zone": { "type": "string" },
"dither_profile": { "type": "string" },
"zone": {
"type": "string"
},
"dither_profile": {
"type": "string"
},
"force_modulation": {
"type": "object",
"properties": {
"harmonic": { "type": "integer" },
"amplitude_n": { "type": "number" },
"phase_deg": { "type": "number" }
"harmonic": {
"type": "integer"
},
"amplitude_n": {
"type": "number"
},
"phase_deg": {
"type": "number"
}
}
},
"acceptance": {
"type": "object",
"additionalProperties": true
},
"notes": { "type": "string" }
"notes": {
"type": "string"
},
"spindle_direction": {
"type": "string",
"enum": [
"cw",
"ccw"
],
"description": "Requested toolhead spindle rotation direction using the same physical convention as polisher-control."
}
}
}
}

View File

@@ -12,7 +12,8 @@
"supported_motion_families",
"force_range_n",
"table_rpm_range",
"spindle_rpm_range"
"spindle_rpm_range",
"supported_spindle_directions"
],
"properties": {
"schema_version": {
@@ -38,7 +39,9 @@
},
"supported_motion_families": {
"type": "array",
"items": { "type": "string" },
"items": {
"type": "string"
},
"minItems": 1
},
"force_range_n": {
@@ -60,22 +63,36 @@
"type": "object",
"description": "Force modulation capabilities. Omit entirely if unknown.",
"properties": {
"supported": { "type": "boolean" },
"max_harmonics": { "type": "integer" },
"max_amplitude_n": { "type": "number" },
"notes": { "type": "string" }
"supported": {
"type": "boolean"
},
"max_harmonics": {
"type": "integer"
},
"max_amplitude_n": {
"type": "number"
},
"notes": {
"type": "string"
}
}
},
"supported_dither_profiles": {
"type": "array",
"items": { "type": "string" },
"items": {
"type": "string"
},
"description": "List of dither profile names the controller can handle. Empty = none supported."
},
"segment_duration_limits": {
"type": "object",
"properties": {
"min_s": { "type": "number" },
"max_s": { "type": "number" }
"min_s": {
"type": "number"
},
"max_s": {
"type": "number"
}
}
},
"pause_resume_support": {
@@ -85,12 +102,23 @@
"type": "array",
"items": {
"type": "object",
"required": ["name", "unit"],
"required": [
"name",
"unit"
],
"properties": {
"name": { "type": "string" },
"unit": { "type": "string" },
"sample_rate_hz": { "type": "number" },
"notes": { "type": "string" }
"name": {
"type": "string"
},
"unit": {
"type": "string"
},
"sample_rate_hz": {
"type": "number"
},
"notes": {
"type": "string"
}
}
}
},
@@ -98,21 +126,46 @@
"type": "object",
"description": "Hard safety limits that the controller enforces regardless of job requests.",
"properties": {
"max_force_n": { "type": "number" },
"max_table_rpm": { "type": "number" },
"max_spindle_rpm": { "type": "number" },
"notes": { "type": "string" }
"max_force_n": {
"type": "number"
},
"max_table_rpm": {
"type": "number"
},
"max_spindle_rpm": {
"type": "number"
},
"notes": {
"type": "string"
}
}
},
"known_constraints": {
"type": "array",
"items": { "type": "string" },
"items": {
"type": "string"
},
"description": "Free-text list of known limitations, quirks, or warnings."
},
"unknowns": {
"type": "array",
"items": { "type": "string" },
"items": {
"type": "string"
},
"description": "Capabilities that have NOT been verified. Explicit unknowns prevent fake certainty."
},
"supported_spindle_directions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"cw",
"ccw"
]
},
"minItems": 1,
"uniqueItems": true,
"description": "Toolhead spindle rotation directions supported by the controller UI/protocol."
}
},
"$defs": {
@@ -120,7 +173,9 @@
"oneOf": [
{
"type": "array",
"items": { "type": "number" },
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "[min, max] range."

View File

@@ -49,7 +49,12 @@
},
"result_state": {
"type": "string",
"enum": ["completed", "completed_with_pause", "aborted", "faulted"]
"enum": [
"completed",
"completed_with_pause",
"aborted",
"faulted"
]
},
"segments": {
"type": "array",
@@ -61,31 +66,72 @@
"commanded_summary": {
"type": "object",
"properties": {
"force_n": { "type": "number" },
"table_rpm": { "type": "number" },
"spindle_rpm": { "type": "number" }
"force_n": {
"type": "number"
},
"table_rpm": {
"type": "number"
},
"spindle_rpm": {
"type": "number"
},
"spindle_direction": {
"type": "string",
"enum": [
"cw",
"ccw"
]
}
}
},
"actual_summary": {
"type": "object",
"properties": {
"force_n_mean": { "type": "number" },
"force_n_min": { "type": "number" },
"force_n_max": { "type": "number" },
"table_rpm_mean": { "type": "number" },
"spindle_rpm_mean": { "type": "number" }
"force_n_mean": {
"type": "number"
},
"force_n_min": {
"type": "number"
},
"force_n_max": {
"type": "number"
},
"table_rpm_mean": {
"type": "number"
},
"spindle_rpm_mean": {
"type": "number"
}
}
},
"alarms": {
"type": "array",
"items": {
"type": "object",
"required": ["timestamp", "code", "message"],
"required": [
"timestamp",
"code",
"message"
],
"properties": {
"timestamp": { "type": "string", "format": "date-time" },
"code": { "type": "string" },
"message": { "type": "string" },
"severity": { "type": "string", "enum": ["info", "warning", "critical"] }
"timestamp": {
"type": "string",
"format": "date-time"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"critical"
]
}
}
}
},
@@ -93,11 +139,21 @@
"type": "array",
"items": {
"type": "object",
"required": ["timestamp", "type"],
"required": [
"timestamp",
"type"
],
"properties": {
"timestamp": { "type": "string", "format": "date-time" },
"type": { "type": "string" },
"detail": { "type": "string" }
"timestamp": {
"type": "string",
"format": "date-time"
},
"type": {
"type": "string"
},
"detail": {
"type": "string"
}
}
}
},
@@ -120,51 +176,107 @@
"result_state"
],
"properties": {
"segment_id": { "type": "string" },
"source_pass_id": { "type": "string" },
"commanded_duration_s": { "type": "number" },
"actual_duration_s": { "type": "number" },
"segment_id": {
"type": "string"
},
"source_pass_id": {
"type": "string"
},
"commanded_duration_s": {
"type": "number"
},
"actual_duration_s": {
"type": "number"
},
"result_state": {
"type": "string",
"enum": ["completed", "completed_with_pause", "aborted", "faulted", "skipped"]
"enum": [
"completed",
"completed_with_pause",
"aborted",
"faulted",
"skipped"
]
},
"commanded": {
"type": "object",
"properties": {
"force_n": { "type": "number" },
"table_rpm": { "type": "number" },
"spindle_rpm": { "type": "number" },
"cam_amplitude_deg": { "type": "number" },
"cam_offset_deg": { "type": "number" }
"force_n": {
"type": "number"
},
"table_rpm": {
"type": "number"
},
"spindle_rpm": {
"type": "number"
},
"cam_amplitude_deg": {
"type": "number"
},
"cam_offset_deg": {
"type": "number"
},
"spindle_direction": {
"type": "string",
"enum": [
"cw",
"ccw"
]
}
}
},
"actual": {
"type": "object",
"properties": {
"force_n_mean": { "type": "number" },
"force_n_min": { "type": "number" },
"force_n_max": { "type": "number" },
"table_rpm_mean": { "type": "number" },
"spindle_rpm_mean": { "type": "number" }
"force_n_mean": {
"type": "number"
},
"force_n_min": {
"type": "number"
},
"force_n_max": {
"type": "number"
},
"table_rpm_mean": {
"type": "number"
},
"spindle_rpm_mean": {
"type": "number"
}
}
},
"pause_windows": {
"type": "array",
"items": {
"type": "object",
"required": ["paused_at", "resumed_at"],
"required": [
"paused_at",
"resumed_at"
],
"properties": {
"paused_at": { "type": "string", "format": "date-time" },
"resumed_at": { "type": "string", "format": "date-time" },
"reason": { "type": "string" }
"paused_at": {
"type": "string",
"format": "date-time"
},
"resumed_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string"
}
}
}
},
"anomaly_flags": {
"type": "array",
"items": { "type": "string" }
"items": {
"type": "string"
}
},
"notes": { "type": "string" }
"notes": {
"type": "string"
}
}
}
}