WIP: update printer api

TODO.md

@@ -46,14 +46,14 @@
   - [x] Retrieve the current bed state
   - [x] Issue a chamber command
   - [x] Retrieve the current chamber state
-  - [ ] Issue an SD command
-  - [ ] Retrieve the current SD state
-  - [ ] Send an arbitrary command to the printer
+  - [x] Issue an SD command
+  - [x] Retrieve the current SD state
+  - [x] Send an arbitrary command to the printer
   - [ ] Retrieve custom controls
-  - [ ] Model: Full State Response
-  - [ ] Model: Temperature State
-  - [ ] Model: SD State
-  - [ ] Model: Arbitrary Command Request
+  - [x] Model: Full State Response
+  - [x] Model: Temperature State
+  - [x] Model: SD State
+  - [x] Model: Arbitrary Command Request
   - [ ] Model: Custom Controls Response
 - [ ] Printer profile operations [link](https://docs.octoprint.org/en/master/api/printerprofiles.html)
   - [ ] Retrieve all printer profiles

openapi/components/requestBodies/ArbitraryPrinterCmd.yaml

@@ -0,0 +1,28 @@
+type: object
+description: >-
+  Arbitrary Command Request
+properties:
+  command:
+    type: string
+    description: >-
+      Single command to send to the printer, mutually exclusive with commands and script.
+  commands:
+    type: array
+    items:
+      type: string
+    description: >-
+      Multiple commands to send to the printer (in the given order), mutually exclusive with command and script.
+  script:
+    type: string
+    description: >-
+      Name of the GCODE script template to send to the printer, mutually exclusive with command and commands.
+  parameters:
+    type: object
+    additionalProperties: true
+    description: >-
+      Key value pairs of parameters to replace in sent commands/provide to the script renderer
+  context:
+    type: object
+    additionalProperties: true
+    description: >-
+      (only if script is set) additional template variables to provide to the script render

openapi/components/requestBodies/PrinterBedCommand.yaml

@@ -0,0 +1,30 @@
+content:
+  application/json:
+    schema:
+      discriminator:
+        propertyName: command
+      oneOf:
+        - type: object
+          description: >-
+            Sets the given target temperature on the printer’s bed.
+          properties:
+            command:
+              type: string
+              enum:
+                - target
+            target:
+              type: number
+              description: >-
+                Target temperature to set. A value of 0 will turn the heater off.
+        - type: object
+          description: >-
+            Sets the given temperature offset on the printer’s bed.
+          properties:
+            command:
+              type: string
+              enum:
+                - offset
+            offset:
+              type: number
+              description: >-
+                Offset to set.

openapi/components/requestBodies/PrinterChamberCommand.yaml

@@ -0,0 +1,30 @@
+content:
+  application/json:
+    schema:
+      discriminator:
+        propertyName: command
+      oneOf:
+        - type: object
+          description: >-
+            Sets the given target temperature on the printer’s chamber.
+          properties:
+            command:
+              type: string
+              enum:
+                - target
+            target:
+              type: number
+              description: >-
+                Target temperature to set. A value of 0 will turn the heater off.
+        - type: object
+          description: >-
+            Sets the given temperature offset on the printer’s chamber.
+          properties:
+            command:
+              type: string
+              enum:
+                - offset
+            offset:
+              type: number
+              description: >-
+                Offset to set.

openapi/components/requestBodies/PrinterSdCommand.yaml

@@ -0,0 +1,17 @@
+content:
+  application/json:
+    schema:
+      type: object
+      description: >-
+        Printer SD card command
+      properties:
+        command:
+          type: string
+          description: >-
+            - `init`: Initializes the printer’s SD card, making it available for use. This also includes an initial retrieval of the list of files currently stored on the SD card, so after issuing that command a retrieval of the files on SD card will return a successful result.
+            - `refresh`: Refreshes the list of files stored on the printer’s SD card. Will return a 409 Conflict if the card has not been initialized yet (see the init command and SD state).
+            - `release`: Releases the SD card from the printer. The reverse operation to init. After issuing this command, the SD card won’t be available anymore, hence and operations targeting files stored on it will fail. Will return a 409 Conflict if the card has not been initialized yet (see the init command and SD state).
+          enum:
+            - init
+            - refresh
+            - release

openapi/components/responses/BedState.yaml

@@ -0,0 +1,26 @@
+"200":
+  description: Current bed status with optional history
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          bed:
+            $ref: ../schemas/printer/TemperatureProbe.yaml
+          history:
+            type: array
+            items:
+              type: object
+              properties:
+                time:
+                  type: integer
+                bed:
+                  $ref: ../schemas/printer/TemperatureProbe.yaml
+              example:
+                time: 1395651928
+                bed:
+                  actual: 50.221
+                  target: 70.0
+"409":
+  description: >-
+    If the printer is not operational or the selected printer profile does not have a heated bed.

openapi/components/responses/ChamberState.yaml

@@ -0,0 +1,26 @@
+"200":
+  description: Current chamber status with optional history
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          chamber:
+            $ref: ../schemas/printer/TemperatureProbe.yaml
+          history:
+            type: array
+            items:
+              type: object
+              properties:
+                time:
+                  type: integer
+                chamber:
+                  $ref: ../schemas/printer/TemperatureProbe.yaml
+              example:
+                time: 1395651928
+                bed:
+                  actual: 50.221
+                  target: 70.0
+"409":
+  description: >-
+    If the printer is not operational or the selected printer profile does not have a heated chamber.

openapi/components/responses/ToolState.yaml

@@ -13,7 +13,7 @@
                 time:
                   type: integer
               additionalProperties:
-                $ref: ../schemas/printer/Tool.yaml
+                $ref: ../schemas/printer/TemperatureProbe.yaml
               example:
                 tool1:
                   actual: 250
@@ -21,4 +21,7 @@
                   actual: 200
                   target: 215
         additionalProperties:
-          $ref: ../schemas/printer/Tool.yaml
+          $ref: ../schemas/printer/TemperatureProbe.yaml
+"409":
+  description: >-
+    If the printer is not operational.

openapi/components/schemas/printer/TemperatureProbe.yaml

@@ -0,0 +1,11 @@
+type: object
+description: Current Tool temperature
+required:
+  - actual
+properties:
+  actual:
+    type: number
+  target:
+    type: number
+  offset:
+    type: number

openapi/openapi.yaml

@@ -46,3 +46,21 @@ paths:
       $ref: paths/printer/tool-get.yaml
     post:
       $ref: paths/printer/tool-post.yaml
+  /printer/bed:
+    get:
+      $ref: paths/printer/bed-get.yaml
+    post:
+      $ref: paths/printer/bed-post.yaml
+  /printer/chamber:
+    get:
+      $ref: paths/printer/chamber-get.yaml
+    post:
+      $ref: paths/printer/chamber-post.yaml
+  /printer/sd:
+    get:
+      $ref: paths/printer/sd-get.yaml
+    post:
+      $ref: paths/printer/sd-post.yaml
+  /printer/command:
+    post:
+      $ref: paths/printer/command-post.yaml

openapi/paths/printer/bed-get.yaml

@@ -0,0 +1,10 @@
+summary: Retrieve the current bed state
+operationId: getBedState
+description: >-
+  Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for the printer’s heated bed.
+  It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history   data points can be limited using the limit query parameter.
+parameters:
+  - $ref: ../../components/parameters/history.yaml
+  - $ref: ../../components/parameters/limit.yaml
+responses:
+  $ref: ../../components/responses/BedState.yaml

openapi/paths/printer/bed-post.yaml

@@ -0,0 +1,16 @@
+summary: Issue a bed command
+operationId: sendBedCmd
+description: >-
+  Bed commands allow setting the temperature and temperature offsets for the printer’s heated bed.
+requestBody:
+  $ref: ../../components/requestBodies/PrinterBedCommand.yaml
+responses:
+  "204":
+    description: >-
+      No Error
+  "400":
+    description: >-
+      If target or offset is not a valid number or outside of the supported range, or if the request is otherwise invalid.
+  "409":
+    description: >-
+      If the printer is not operational or the selected printer profile does not have a heated bed.

openapi/paths/printer/chamber-get.yaml

@@ -0,0 +1,11 @@
+summary: Retrieve the current chamber state
+operationId: getChamberState
+description: >-
+  Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for the printer’s heated chamber.
+
+  It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history data points can be limited using the limit query parameter.
+parameters:
+  - $ref: ../../components/parameters/history.yaml
+  - $ref: ../../components/parameters/limit.yaml
+responses:
+  $ref: ../../components/responses/ChamberState.yaml

openapi/paths/printer/chamber-post.yaml

@@ -0,0 +1,16 @@
+summary: Issue a bed command
+operationId: sendChamberCmd
+description: >-
+  Chamber commands allow setting the temperature and temperature offsets for the printer’s heated chamber.
+requestBody:
+  $ref: ../../components/requestBodies/PrinterChamberCommand.yaml
+responses:
+  "204":
+    description: >-
+      No Error
+  "400":
+    description: >-
+      If target or offset is not a valid number or outside of the supported range, or if the request is otherwise invalid.
+  "409":
+    description: >-
+      If the printer is not operational or the selected printer profile does not have a heated chamber.

openapi/paths/printer/command-post.yaml

@@ -0,0 +1,13 @@
+summary: Send an arbitrary command to the printer
+operationId: sendPrinterCmd
+description: >-
+  Sends any command to the printer via the serial interface. Should be used with some care as some commands can interfere with or even stop a running print job.
+requestBody:
+  content:
+    application/json:
+      schema:
+        $ref: ../../components/requestBodies/ArbitraryPrinterCmd.yaml
+responses:
+  "204":
+    description: >-
+      No error

openapi/paths/printer/sd-get.yaml

@@ -0,0 +1,21 @@
+summary: Retrieve the current SD state
+operationId: getSdState
+description: >-
+  Retrieves the current state of the printer’s SD card. For this request no authentication is needed.
+
+  If SD support has been disabled in OctoPrint’s settings, a 404 Not Found is returned.
+
+  Returns a 200 OK with an SD State Response in the body upon success.
+responses:
+  "200":
+    description: >-
+      SD State Response
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            ready:
+              type: boolean
+  "409":
+    description: If SD support has been disabled in OctoPrint’s config.

openapi/paths/printer/sd-post.yaml

@@ -0,0 +1,13 @@
+summary: Issue an SD command
+operationId: sendSdCmd
+description: >-
+  SD commands allow initialization, refresh and release of the printer’s SD card (if available).
+requestBody:
+  $ref: ../../components/requestBodies/PrinterSdCommand.yaml
+responses:
+  "204":
+    description: >-
+      No error
+  "409":
+    description: >-
+      If a refresh or release command is issued but the SD card has not been initialized (e.g. via init.

openapi/paths/printer/tool-get.yaml

@@ -6,4 +6,4 @@ parameters:
   - $ref: ../../components/parameters/history.yaml
   - $ref: ../../components/parameters/limit.yaml
 responses:
-  $ref: ../../components/responses/ToolStatus.yaml
+  $ref: ../../components/responses/ToolState.yaml