Formide

Formide Developer Documentation

3D printing for developers!

Get Started

Get started

Formide allows manufacturers of 3D printers to connect their printer to the cloud. The easiest way this can be done by using Printr's open source formide-client software (available on GitHub).

When using Formide client, there is also the option to build a touch screen interface using QT. To get you started quickly, we provide a data library and default interface that you can build on top of. These resources, including documentation, are also available on GitHub.

Another option is to build a custom integration to connect the printer to Formide, handle authentication and download G-code files from the queue. This document explains into detail how such a custom integration should be set up by listing the needed components and code snippets. Furthermore, the relevant cloud HTTP API endpoints for manufacturers are listed at here.

Components

To create a fully working custom integration, you need at least the following parts:

  1. A white-listed hardware device (using the MAC address). We advice to use our custom integratable hardware or Raspberry Pi.
  2. A real-time (RTM) API connection to Formide using Socket.io.
  3. An authentication RTM event to get the printer online.
  4. Emitting and listening to events over the RTM connection to interact with the Formide platform, for example to update the printer status.
  5. HTTP calls to the API to get the queue, download G-code files and connect the printer to a user account.
  6. Optionally, an HTTP call to remove an item from the cloud queue. This is automatically done when a print job finishes, but if it's stopped before finishing, the item remains in the queue. A queue item can also be removed from the Formide platform interface.
  7. Optionally, listening to HTTP proxy events to allow things like manually controlling the printer via the Formide cloud interface.

RTM Connection

The Formide Cloud API accepts real-time connections from 3D printers (also known as 'devices') using Socket.io. Socket.io is a popular library for real-time communication in primarily JavaScript environments (but also other languages like Java, C++ and Swift are supported).

The RTM API can also be used by application developers to listen to the events that are emitted by printers. For more information on this read the Get started section of the RTM documentation.

Authentication

To authenticate to Formide using the RTM API, your device's MAC address first needs to be white-listed. Only connections from white-listed devices are accepted by the API. To authenticate, you can emit the authentication event over the RTM connection after the connection opened.

The following codes snippet is an example on how to add this to a JavaScript based web page.

var socket = io('https://api.formide.com')

// the connect event listener is triggered when the connection has been opened
socket.on('connect', function () {

    // after connecting, we emit the authentication event
    socket.emit('authenticate', {
        type: 'client',
        ip: '',
        ip_internal: '192.160.0.10',
        mac: '',
        version: '2.0.0',
        environment: 'production'
    }, function (response) {
        // we receive a response from the server in the callback function
        console.log('success', response.success)
    })
})

socket.on('disconnect', function () {
    // here you can handle neede disconnection logic, like showing a warning to the user
})

Request parameters

Here is a list of the authentication parameters and their descriptions.

Parameter Description
type Connection type, must be client
ip Current external IP address
ip_internal Current internal IP address
mac White-listed MAC address
version Version of your client software is running
environment Which environment of your client sofware is running

Response parameters

Here is a list of parameters that the API response will contain in the callback.

Parameter Description
success A boolean indicating if the authentication was successful.
deviceToken A token that can be used to do HTTP API calls to fetch the print queue and download G-code files. Should not be confused with an access token, which is used by logged-in users to do API calls.

After authentication was successful, your printer is ready to receive and emit events. An example implementation can be found here.

Emitting events

Emitting events can be done by calling the socket.emit of Socket.io. The first parameter is the event name, the second parameter is the event data and the third parameter is a callback function. The callback function contains an error if incorrect event data was sent to the API.

socket.emit('printer.connected', {
  port: '/dev/ttyUSB0'
}, function (error) {
  // this function contains an error object if the event data was incorrect
  console.error('cloud event error', error)
})

Printer connected

Emit the event printer.connected over the websocket to indicate a printer has been connected. This triggers a setup popup on Formide if the printer port hasn't been connected to a database entry before.

Parameter Description
port The serial/USB port on which the printer is connected

Printer disconnected

Emit the event printer.disconnected to indicate a printer has been disconnected.

Parameter Description
port The serial/USB port on which the printer disconnected from

Printer status

Emit the event printer.status to indicate a status change in the printer. It is adviced to send this event every 2 seconds, wether there is specific activity or not.

Parameter Description
port The serial/USB port on which the printer is connected
status The status of the printer, can be offline, connecting, online, heating, printing, paused, stopping.
progress The progress of the current print job as integer ranging from 0 to 100. When nothing is printing, you should send 0.
queueItemId The ID of the queue item if the print was started from the cloud. The platform uses this ID to show the correct details about the printing item.

Printer started

Emit the event printer.started when a print job has started printing.

Parameter Description
port The serial/USB port of the printer.

Printer paused

Emit the event printer.paused when a print job has paused printing.

Parameter Description
port The serial/USB port of the printer.

Printer resumed

Emit the event printer.resumed when a print job has resumed printing.

Parameter Description
port The serial/USB port of the printer.

Printer stopped

Emit the event printer.stopped when a print job has stopped printing (but did not finish yet!).

Parameter Description
port The serial/USB port of the printer.

Printer finished

Emit the event printer.finished when a print job has finished printing.

Parameter Description
port The serial/USB port of the printer.
queueItemId The ID of the cloud queue item that finished printing. This will set the queue item state to 'finished' and remove it from the queue list.

Receiving events

The cloud will send events to the printer when something needs to happen. You can listen to those by using the socket.on function in Socket.io.

Starting a cloud print

Listen to the printQueueItem event to handle printing a G-code from the cloud queue. The first thing that should be done is downloading the G-code file that is attached to queue item. Then, the printer should start printing this G-code immediately, as this event is triggered when the user hits 'print' in the cloud interface. An example implementation of this flow can be found in formide-client-2, where we also make use of the MD5 checksum HTTP header to verify if a file has been fully transferred.

socket.on('printQueueItem', function (data) {
  // implementation to download the G-code for the queue item and start the print
})

HTTP calls

Generate a cloud code

In order to pair a 3D printer to a Formide account, a cloud code has to be requested from the API. This endpoint is fully documented in our API reference.

An example implementation can be found in formide-client-2.

Queueing

You can fetch the cloud queue for your printer by using the queue as device endpoint of the Formide API. This endpoint is fully documented in our API reference.

An example implementation can be found in formide-client-2.

G-code downloading

To download a G-code file to your printer, you can use the G-code download endpoint of the Formide API. This endpoint is fully documented in our API reference.

An example implementation can be found in formide-client-2. In this example e also make use of the MD5 checksum HTTP header to verify if a file has been fully transferred.

Removing a queue item

To remove a queue item from the cloud queue you can use a Formide API endoint. This endpoint is fully documented in our API reference.

An example implementation can be found in formide-client-2.

Get started