Web API

Introduction

Prunt provides HTTP and WebSocket APIs for interacting with the host.

JSON Object Schemas

The configuration and status objects are represented as JSON. Because the available modules may change depending on the setup, the schemas describe the layout rather than listing specific modules.

Configuration Schema

The configuration schema details the types and constraints for the properties of all loaded modules.

{
   "Prunt config version": 1,
   "Config": {
        "<Module Name>": {
            "Version": number,
            "Config": {
                ...
            }
        },
        ...
    }
}

• Prunt_Config_Version is currently always 1 and will change if the schema defined here changes.
• The top level Config component contains zero or more named modules containing user-configurable properties.
• The Version component of a module is incremented each time a modules available properties change, this does not change when the user-configured values within properties change.
• The Config component of a module contains zero or more named user-configurable properties defined in the following section.

Property Kinds in Configuration Schema

All properties contain Kind and Description components, which are strings. Other components are determined by the value of the Kind component.

{
     "Kind": string,
     "Description": string,
     ...
}

{
    "Kind": "Boolean",
    "Description": string,
    "Default": boolean
}

{
    "Kind": "Discrete",
    "Description": string,
    "Options": [string, ...],
    "Default": string
}

{
    "Kind": "Integer",
    "Description": string,
    "Min": number,
    "Max": number,
    "Unit": string,
    "Default": number
}

{
    "Kind": "Float",
    "Description": string,
    "Min": number,
    "Max": number,
    "Unit": string,
    "Default": number
}

{
    "Kind": "Float_Ratio",
    "Description": string,
    "Min": number,
    "Max": number,
    "Default_Numerator": number,
    "Default_Denominator": number
}

{
    "Kind": "Sequence",
    "Tabbed": boolean,
    "Description": string,
    "Children": {...}
}

• A sequence groups together multiple properties which are all active as long as the sequence is.
• The Children component of a sequence contains named configuration properties from this section.
• The Tabbed component of a sequence hints that the children should be shown as tabs in a GUI.

{
   "Kind": "Variant",
   "Description": string,
   "Default": string,
   "Children": {...}
}

• A variant allows selection of exactly one of its children to be active.
• The Children component of a variant contains named configuration properties from this section.

Configuration Values

This represents the current configuration, mirroring the hierarchy of the configuration schema above.

{
    "Prunt config version": 1,
    "Config": {
        "<Module Name>": {
            "Version": 1,
            "Config": {
                ...
            }
        }
    }
}

• For Float_Ratio the value is {"Numerator": number, "Denominator": number}.
• For Variant, it is {"Selected": string, "Children": {"<Variant Name>": ..., ...}} and non-selected children are present.
• For Sequence, it is {"<Property Name>": ..., ...}.

Status Schema

The status schema defines the real-time telemetry variables.

{
    "<Module Name>": {
        "<Group Name>": {
            "<Value Name>": {
                "Kind": "Real | Integer | Boolean | String",
                "Unit": "string",
                "Description": "string",
                "Condition": "string"
            }
        }
    }
}

Condition contains a string detailing when the value will be present.

Status Values

{
  "<Module Name>": {
    "<Group Name>": {
        "<Value Name>": number | boolean | string
    }
  }
}

• Values, groups, and modules may not be present if a value has not yet been provided by the module.
• Only components which appear in the status schema object above will appear here.

HTTP API Endpoints

Configuration

GET /config/schema

Returns the JSON Configuration Schema detailing all configuration blocks across available modules.

GET /config/values

Returns the current Configuration Values.

The response may contain a list of errors which can only be detected server-side. These should be displayed to the user under the relevant properties.

{
    "Values": { /* Configuration Values object */ },
    "Errors": [
        {
            "Path": ["Config", "<Module Name>", "Config", "<Property Name>", ...],
            "Message": string
        },
        ...
    ]
}

POST /config/values

Patches the existing configuration with new values. This may be a partial object containing just the fields to be updated, however the top level version field and the version field of any modules to be updated are required.

The response may contain a list of errors which can only be detected server-side. These should be displayed to the user under the relevant properties.

If the constraints in the schema are violated then the configuration will not be updated.

{
    "Values": { /* Updated Configuration Values object */ },
    "Errors": [
        {
            "Path": ["Config", "<Module Name>", "Config", "<Property Name>", ...],
            "Message": string
        },
        ...
    ]
}

Status

GET /status/schema

Returns the JSON Status Schema detailing all telemetry variables available.

GET /status/values

Returns the current JSON Status Values snapshot.

Machine Control

POST /pause/pause

Pauses the machine step generator.

POST /pause/resume

Resumes the machine step generator.

POST /run-file

Submits an uploaded G-code file for execution. The body should be a string containing the file name.

Responses:

• 204 No Content: Submission successful.
• 500 Internal Server Error: Refer to reply body.

POST /run-command

Submits a G-code command string for execution. The body should be a string containing the command to run.

Responses:

• 204 No Content: Submission successful.
• 500 Internal Server Error: Refer to reply body.

POST /reload-server

Forces a restart of the host application.

File Management

GET /uploads/

Retrieves a list of files existing in the system’s uploads directory.

The respong body will be a JSON array of strings.

GET /uploads/<filename>

Downloads an uploaded file.

PUT /uploads/<filename>

Uploads or overwrites a file in the system’s uploads directory.

Maintenance & Static Content

GET /update-check

Checks if a host software update is available. This does not perform an update check but instead just retrieves the result of the last check if one is available.

May reply with 500 if the update check times out, otherwise will reply similar to:

{
    "Available": boolean,
    "URL": string
}

POST /allow-firmware-update

Grants permission via the UI to apply a firmware update (prevents looping unattended updates).

WebSocket API

The server provides a single WebSocket endpoint for real-time logs and status variables at /websocket/everything.

Server to Client Messages

Startup Notification

Fired once after connection and when the host application is restarted. This can be used to check if the page needs to be forcefully reloaded.

{
    "Server_Start_Time": string
}

Periodical Update

{
    "Status_Values": { /* Status Values object */ },
    "Startup": "Done | Update_Running | Update_Required | Waiting"
}

• If Startup is Update_Required then /allow-firmware-update must be posted to for a required firmware update.
• If Startup is Update_Running or Waiting then the machine has not yet finished startup.

Log Statements

{
    "Log": string
}

Client to Server Messages

The client is permitted to send a plaintext positive integer to throttle the status updates.

Periodical updates will only be broadcast to the client every Nth status tick (currently 50 ms).