OctoPrintClient.socket

OctoPrintClient.socket.options

The socket client’s options.

OctoPrintClient.socket.options.timeouts

A list of consecutive timeouts after which to attempt reconnecting to a disconnected sockets, in seconds. Defaults to [1, 1, 2, 3, 5, 8, 13, 20, 40, 100]. The default setting here makes the client slowly back off after the first couple of very fast connection attempts don’t succeed, and give up after 10 tries.

OctoPrintClient.socket.options.rateSlidingWindowSize

Number of last rate measurements to take into account for timing analysis and communication throttling. See Communication Throttling below.

OctoPrintClient.socket.connect(opts)

Connects the socket client to OctoPrint’s SockJS socket.

The optional parameter opts may be used to provide additional configuration options to the SockJS constructor. See the SockJS documentation on potential options.

Arguments:

  • opts (object()) – Additional options for the SockJS constructor.

OctoPrintClient.socket.reconnect()

Reconnects the socket client. If the socket is currently connected it will be disconnected first.

OctoPrintClient.socket.disconnect()

Disconnects the socket client.

OctoPrintClient.socket.onMessage(message, handler)

Registers the handler for messages of type message.

To register for all message types, provide * as the type to register for.

handler is expected to be a function accepting one object parameter eventObj, consisting of the received message as property event and the received payload (if any) as property data.

OctoPrint.socket.onMessage("*", function(message) {
    // do something with the message object
});

The socket client will measure how long message processing over all handlers will take and utilize that measurement to determine if the communication throttling needs to be adjusted or not.

Please refer to the Push API documentation for details on the possible message types and their payloads.

Arguments:

  • message (string()) – The type of message for which to register

  • handler (function()) – The handler function

OctoPrintClient.socket.removeMessage(message, handler)

Removes the handler for messages of type message.

const handler = (message) => {
    // do something with the message object
};

OctoPrint.socket.onMessage("*", handler);
// Use the same reference to the handler function to remove it again
OctoPrint.socket.removeMessage("*", handler);
Arguments:

  • message (string()) – The type of message for which to remove the handler

  • handler (function()) – The handler function

OctoPrintClient.socket.sendMessage(type, payload)

Sends a message of type type with the provided payload to the server.

Note that at the time of writing, OctoPrint only supports the throttle and auth messages. See also the Push API documentation.

Arguments:

  • type (string()) – Type of message to send

  • payload (object()) – Payload to send

OctoPrintClient.socket.sendAuth(userId, session)

Sends an auth message with the provided userId and session to the server.

session is expected to be the session value retrieved from any valid OctoPrint.browser.login(userId,…) response.

See also the Push API documentation.

Arguments:

  • userId (string()) – An existing OctoPrint username

  • session (string()) – A valid session id for the provided username

OctoPrintClient.socket.onRateTooLow(measured, minimum)

Called by the socket client when the measured message round trip times have been lower than the current lower processing limit over the full sliding window, indicating that messages are now processed faster than the current rate and a faster rate might be possible.

Can be overwritten with custom handler methods. The default implementation will call OctoPrint.socket.increaseRate().

Arguments:

  • measured (Number()) – Maximal measured message round trip time

  • minimum (Number()) – Lower round trip time limit for keeping the rate

OctoPrintClient.socket.onRateTooHigh(measured, maximum)

Called by the socket client when the last measured round trip time was higher than the current upper processing limit, indicating that the messages are now processed slower than the current rate requires and a slower rate might be necessary.

Can be overwritten with custom handler methods. The default implementation will call OctoPrint.socket.decreaseRate().

Arguments:

  • measured (Number()) – Measured message round trip time

  • minimum (Number()) – Upper round trip time limit for keeping the rate

OctoPrintClient.socket.increaseRate()

Instructs the server to increase the message rate by 500ms.

OctoPrintClient.socket.decreaseRate()

Instructs the server to decrease the message rate by 500ms.

Sample to setup an authed socket

If you have a username and a password:

OctoPrint.socket.connect();
OctoPrint.browser.login("myusername", "mypassword", true)
    .done(function(response) {
        OctoPrint.socket.sendAuth("myusername", response.session);
    });

If you have an API key:

var client = new OctoPrintClient({
    baseurl: "http://example.com/",
    apikey: "abcdef"
});
client.socket.connect();
client.browser.passiveLogin()
    .done(function(response) {
        client.socket.sendAuth(response.name, response.session);
    });

Communication Throttling

The socket client supports communication throttling. It will measure how long each incoming message takes to be processed by all registered handlers. If the processing times in a sliding window are longer than the current rate limit configured on the socket (default: 500ms between messages), the socket client will instruct the server to send slower. If the messages are handled faster than half the current rate limit, the socket client will instruct the server to send faster.