Rest API /api/v2

docs/rest-api.md

@@ -0,0 +1,235 @@
+# REST API `/api/v2`
+
+The Qitech Control Panel exposes a small HTTP interface for discovering machines and reading their current values. All examples below assume you are connected to the panel’s Ethernet subnet and talk directly to the panel at:
+
+- **Base URL:** `http://10.10.10.1:3001`
+
+> **Schema note:** This documentation intentionally stays light on field details beyond what is shown in the examples. For the exact datatypes and complete payload shapes, refer to the corresponding Rust types (linked below).
+
+---
+
+## Authentication
+
+The panel does **not** perform HTTP authentication. The expected security model is **network-level isolation**: anything that can send packets to the panel’s Ethernet interface is treated as trusted. This matches common security assumptions in EtherCAT-style control networks.
+
+The panel is configured to administer its own subnet `10.10.10.0/24` via DHCP, while Wi-Fi can be used for upstream internet connectivity (if configured). If you need authentication or access from outside the isolated subnet, place a router/device in **client/bridge mode** on the panel network and expose the panel through a **reverse proxy** where you can add authentication, logging, rate limiting, etc.
+
+If DNS is available on the subnet, you may be able to resolve `qitech.control`; otherwise use the static address `10.10.10.1`.
+
+---
+
+## List machines `GET /api/v2/machine`
+
+Returns the set of machines currently known/connected to the panel.
+
+Machines are identified by:
+
+- `slug`: the machine type / model identifier (string)
+- `serial`: the specific machine instance identifier (int)
+
+Each machine also includes a `legacy_id` to support older **v1** workflows. If a machine reports an issue, the `error` field may be present and non-null (containing an error message).
+
+### Example request
+
+```bash
+curl -X GET "http://10.10.10.1:3001/api/v2/machine"
+```
+
+### Example response
+
+```json
+{
+  "machines": [
+    {
+      "legacy_id": {
+        "machine_identification": {
+          "vendor": 1,
+          "machine": 7
+        },
+        "serial": 57922
+      },
+      "serial": 57922,
+      "vendor": "QiTech",
+      "slug": "mock",
+      "error": null
+    },
+    {
+      "legacy_id": {
+        "machine_identification": {
+          "vendor": 1,
+          "machine": 4
+        },
+        "serial": 57922
+      },
+      "serial": 57922,
+      "vendor": "QiTech",
+      "slug": "extruder_v1",
+      "error": null
+    },
+    {
+      "legacy_id": {
+        "machine_identification": {
+          "vendor": 1,
+          "machine": 2
+        },
+        "serial": 57922
+      },
+      "serial": 57922,
+      "vendor": "QiTech",
+      "slug": "winder_v1",
+      "error": null
+    },
+    {
+      "legacy_id": {
+        "machine_identification": {
+          "vendor": 1,
+          "machine": 10
+        },
+        "serial": 48879
+      },
+      "serial": 48879,
+      "vendor": "QiTech",
+      "slug": "wago_power_v1",
+      "error": null
+    }
+  ]
+}
+```
+
+---
+
+## Get current values `GET /api/v2/machine/<slug>/<serial>`
+
+Returns all currently known values for a single machine.
+
+Values are categorized into two groups:
+
+- **State**: requested/commanded values (these typically change only after a state-change request, or if another controller updates them)
+- **Live Values**: measured/observed values coming from the machine and potentially changing quickly
+
+This REST endpoint returns **only the current snapshot**, not a stream of live values.
+To receive continuous updates (via WebSockets), subscribe to the machine namespace (see **WebSockets** below).
+
+### Example request (mock machine)
+
+```bash
+curl -X GET "http://10.10.10.1:3001/api/v2/machine/mock/57922"
+```
+
+### Example response
+
+```json
+{
+  "machine": {
+    "legacy_id": {
+      "machine_identification": {
+        "vendor": 1,
+        "machine": 7
+      },
+      "serial": 57922
+    },
+    "serial": 57922,
+    "vendor": "QiTech",
+    "slug": "mock",
+    "error": null
+  },
+  "state": {
+    "frequency1": 100.0,
+    "frequency2": 200.0,
+    "frequency3": 500.0,
+    "is_default_state": false,
+    "mode_state": {
+      "mode": "Running"
+    }
+  },
+  "live_values": {
+    "amplitude1": -0.03438523433309566,
+    "amplitude2": -0.06872980145477608,
+    "amplitude3": -0.1711138370170743,
+    "amplitude_sum": -0.27422887280494607
+  }
+}
+```
+
+---
+
+## Change machine state `POST /api/v1/machine/<slug>/<serial>`
+
+State changes are submitted as **mutations**. The mutation payload is defined per machine type in Rust. Conceptually, each item in the mutation list represents a setter-style operation that is applied by the real-time control loop.
+
+The API does **not** return the newly-applied state in the POST response. The panel runs a real-time loop and generally won’t block waiting for the physical system to converge. Instead:
+
+- Submit the mutation via `POST`
+- Poll `GET /api/v2/machine/<slug>/<serial>` to observe the updated state and/or any reported errors
+
+### Example request (mock machine)
+
+```bash
+curl -X POST \
+  -d  \
+  -H "Content-Type: application/json" \
+  "http://10.10.10.1:3001/api/v1/machine/mock/57922"
+```
+
+### Example response
+
+```json
+null
+```
+
+---
+
+## WebSockets
+
+For continuous updates, subscribe to a machine-specific namespace derived from its `legacy_id`:
+
+- Namespace: `/machine/<vendor>/<id>/<serial>`
+
+The stream emits events for:
+
+- state changes (`StateEvent`)
+- live value updates (`LiveValuesEvent`)
+
+Both event payloads use the same machine-specific schema as the `/api/v2` REST responses.
+
+---
+
+## List of all machines
+
+Below is a template you can fill with links to the relevant Rust types (mutations + state/live structs).
+For each machine, link to:
+
+- **Mutations:** the request payload type used by `POST /api/v1/machine/<slug>/<serial>`
+- **State / Live Values:** the response payload types returned by `GET /api/v2/machine/<slug>/<serial>`
+
+### Machines
+
+- **winder_v1**
+
+  - Mutations: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/winder2/api.rs#L87>
+  - State: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/winder2/api.rs#L163>
+  - Live Values: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/winder2/api.rs#L143>
+
+- **extruder_v1**
+
+  - Mutations: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/extruder1/api.rs#L214>
+  - State: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/extruder1/api.rs#L89>
+  - Live Values: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/extruder1/api.rs#L55>
+
+- **laser_v1**
+
+  - Mutations: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/laser/api.rs#L88>
+  - State: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/laser/api.rs#L32>
+  - Live Values: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/laser/api.rs#L17>
+
+- **mock**
+
+  - Mutations: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/mock/api.rs#L84>
+  - State: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/mock/api.rs#L38>
+  - Live Values: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/mock/api.rs#L24>
+
+- **extruder_v2**
+
+  - Mutations: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/extruder2/api.rs#L126>
+  - State: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/extruder2/api.rs#L93>
+  - Live Values: <https://github.com/qitechgmbh/control/blob/1ec20074e9030a0ed1739ca9d9a77e298a2652a3/machines/src/extruder2/api.rs#L59>

machines/src/analog_input_test_machine/act.rs

@@ -1,21 +1,32 @@
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
-use crate::{MachineAct, analog_input_test_machine::AnalogInputTestMachine};
+use crate::{
+    MachineAct, MachineMessage, MachineValues, analog_input_test_machine::AnalogInputTestMachine,
+};
 
 impl MachineAct for AnalogInputTestMachine {
-    fn act_machine_message(&mut self, msg: crate::MachineMessage) {
+    fn act_machine_message(&mut self, msg: MachineMessage) {
         match msg {
-            crate::MachineMessage::SubscribeNamespace(namespace) => {
+            MachineMessage::SubscribeNamespace(namespace) => {
                 self.namespace.namespace = Some(namespace);
                 self.emit_measurement_rate();
             }
-            crate::MachineMessage::UnsubscribeNamespace => self.namespace.namespace = None,
-            crate::MachineMessage::HttpApiJsonRequest(value) => {
+            MachineMessage::UnsubscribeNamespace => self.namespace.namespace = None,
+            MachineMessage::HttpApiJsonRequest(value) => {
                 use crate::MachineApi;
                 let _res = self.api_mutate(value);
             }
             crate::MachineMessage::ConnectToMachine(_machine_connection) => {}
-            crate::MachineMessage::DisconnectMachine(_machine_connection) => {}
+            MachineMessage::DisconnectMachine(_machine_connection) => {}
+            MachineMessage::RequestValues(sender) => {
+                sender
+                    .send_blocking(MachineValues {
+                        state: serde_json::Value::Null,
+                        live_values: serde_json::Value::Null,
+                    })
+                    .expect("Failed to send values");
+                sender.close();
+            }
         }
     }
 

machines/src/aquapath1/act.rs

@@ -1,5 +1,5 @@
 use super::{AquaPathV1, AquaPathV1Mode};
-use crate::{MachineAct, MachineMessage};
+use crate::{MachineAct, MachineMessage, MachineValues};
 use std::time::{Duration, Instant};
 
 impl MachineAct for AquaPathV1 {
@@ -45,14 +45,21 @@ impl MachineAct for AquaPathV1 {
                 let _res = self.api_mutate(value);
             }
             MachineMessage::ConnectToMachine(_machine_connection) =>
-            /*Doesnt connect to any Machine so do nothing*/
-            {
-                ()
-            }
+                /*Doesnt connect to any Machine so do nothing*/
+                {}
             MachineMessage::DisconnectMachine(_machine_connection) =>
-            /*Doesnt connect to any Machine so do nothing*/
-            {
-                ()
+                /*Doesnt connect to any Machine so do nothing*/
+                {}
+            MachineMessage::RequestValues(sender) => {
+                sender
+                    .send_blocking(MachineValues {
+                        state: serde_json::to_value(self.get_state())
+                            .expect("Failed to serialize state"),
+                        live_values: serde_json::to_value(self.get_live_values())
+                            .expect("Failed to serialize live values"),
+                    })
+                    .expect("Failed to send values");
+                sender.close();
             }
         }
     }

machines/src/aquapath1/mod.rs

@@ -109,8 +109,8 @@ impl std::fmt::Display for AquaPathV1 {
 }
 
 impl AquaPathV1 {
-    pub fn emit_live_values(&mut self) {
-        let live_values = LiveValuesEvent {
+    pub fn get_live_values(&self) -> LiveValuesEvent {
+        LiveValuesEvent {
             front_temperature: self
                 .front_controller
                 .current_temperature
@@ -123,13 +123,16 @@ impl AquaPathV1 {
             back_flow: self.back_controller.current_flow.get::<liter_per_minute>(),
             front_temp_reservoir: self.front_controller.temp_reservoir.get::<degree_celsius>(),
             back_temp_reservoir: self.back_controller.temp_reservoir.get::<degree_celsius>(),
-        };
-        let event = live_values.build();
+        }
+    }
+
+    pub fn emit_live_values(&mut self) {
+        let event = self.get_live_values().build();
         self.namespace.emit(AquaPathV1Events::LiveValues(event));
     }
 
-    pub fn emit_state(&mut self) {
-        let state = StateEvent {
+    pub fn get_state(&self) -> StateEvent {
+        StateEvent {
             is_default_state: false,
             mode_state: ModeState {
                 mode: self.mode.clone(),
@@ -167,9 +170,11 @@ impl AquaPathV1 {
                     should_flow: self.back_controller.should_pump,
                 },
             },
-        };
+        }
+    }
 
-        let event = state.build();
+    pub fn emit_state(&mut self) {
+        let event = self.get_state().build();
         self.namespace.emit(AquaPathV1Events::State(event));
     }
 }

machines/src/buffer1/act.rs

@@ -1,5 +1,5 @@
 use super::BufferV1;
-use crate::{MachineAct, MachineMessage};
+use crate::{MachineAct, MachineMessage, MachineValues};
 use std::time::{Duration, Instant};
 
 impl MachineAct for BufferV1 {
@@ -33,14 +33,21 @@ impl MachineAct for BufferV1 {
                 let _res = self.api_mutate(value);
             }
             MachineMessage::ConnectToMachine(_machine_connection) =>
-            /*Doesnt connect to any Machine so do nothing*/
-            {
-                ()
-            }
+                /*Doesnt connect to any Machine so do nothing*/
+                {}
             MachineMessage::DisconnectMachine(_machine_connection) =>
-            /*Doesnt connect to any Machine so do nothing*/
-            {
-                ()
+                /*Doesnt connect to any Machine so do nothing*/
+                {}
+            MachineMessage::RequestValues(sender) => {
+                sender
+                    .send_blocking(MachineValues {
+                        state: serde_json::to_value(self.get_state())
+                            .expect("Failed to serialize state"),
+                        live_values: serde_json::to_value(self.get_live_values())
+                            .expect("Failed to serialize live values"),
+                    })
+                    .expect("Failed to send values");
+                sender.close();
             }
         }
     }