Machine update format

This format is used for updating machines manually and internally by the proxy.

Fields

success

boolean, assumed true if omitted

Set to true only if the request to the machine came back with data. Otherwise, provide information about the failure in alerts.

The server will not update the last contact time when this is false.

part_count

unsigned 32-bit integer, omit or null if unknown as 0 will reset the part counter

Monotonically increasing, but can be reset to zero. If this decreases between two reports, the server will assume part counting has started over and parts will not be counted until it increases again.

cycle_state

string, omit or null if unknown

As of server version 4.10.3, users can customize the states and set the cycle_state values that map to each one.

estopped

boolean, omit or null if unknown

true if emergency stopped, false otherwise.

program_name

string, omit or null if unknown as an empty string will be replaced with “(No Program)”

Ideally matches the control’s program name display, but can fall back to O# if reading program names/comments isn’t supported.

A program will be created on the server each time this is set to a value that a particular machine hasn’t reported before.

An empty string indicates we do not know the program name. This will show up in OnTakt as “(No Program)”.

alarms

array of alarm objects, omit or null if unknown as [] means there are no alarms present

Each alarm object can have the following properties:

Key	Type	Default	Description
timestamp	float	Current timestamp	UNIX timestamp representing the start of the alarm
alarm_code	string	""	Alarm code reported by the machine (usually numeric)
alarm_type	string	""	Alarm name reported by the machine
custom_message	string	""	Alarm message looked up from a list of known codes
info	object	{}	Any other key/value data to store with the alarm

At least one of alarm_code or alarm_type must be provided, but ideally both. If neither has a value, the server will reject the machine update. All other fields are optional and will default to the value specified in the table above if omitted or null.

Note

The custom_message field will be overwritten by the server if the user has mapped the alarm type or code to a custom message for this machine.

Detection of new vs. continuing alarms

An alarm should be reported in every machine state update until it has been cleared from the control. The server will only create a new Alarm record if an alarm in the state update is not considered equal to any current alarms on the machine.

An alarm object in this array is considered equal to an existing alarm if they both have the same values for alarm_type, alarm_code, and info (key order doesn’t matter), but timestamp and custom_message are ignored.

Properties are set to their empty defaults (specified in the table above) before comparison. For example, an alarm with a alarm_code of "" would be considered the same as an alarm without an alarm_code entry at all, assuming all the other checked fields are the same as well.

common_vars

map of 16-bit integer to 64-bit float, omit or null if unknown as {} means there are no variables reporting

Maps variable number to the value of each variable.

Keys must be integers, but values can each be an integral or floating-point number, and consistency between the two is not required.

feed_rate_override

nullable integer, omit or null if unknown as 0 means 0%

The current feed rate override as an integral percentage (for example, 100% would be stored as 100).

rapid_override

nullable integer, omit or null if unknown as 0 means 0%

The current rapid override as an integral percentage (for example, 100% would be stored as 100).

active_tool

nullable integer, omit or null if unknown as 0 may be a valid tool number

The number/index of the tool currently in use on the machine.

This corresponds to the location field of tool assemblies.

For machines that use multiple tools simultaneously, this can be the most recently called tool.

alerts

array of strings, omit or null if unknown as [] will clear current alerts

A list of OnTakt system alerts that we should communicate to the user.

For example, “Not reporting common variables”.

If a machine update provides an array of alert messages, they will be shown in a new alert in the Alerts panel.

These are different from alarms in that alarms are generated by the control, while alerts are generated by the application interfacing with the control.

Examples

Everything but the kitchen sink

{
    "success": true,
    "part_count": 42,
    "cycle_state": "STOPPED",
    "estopped": true,
    "program_name": "TEST.MIN",
    "alarms": [
        {
            "timestamp": 1663713768,
            "alarm_type": "VOLTAGE FLUTTER",
            "alarm_code": 1160,
            "info": {
                "type": "SYSTEM"
            }
        },
        {
            "timestamp": 1663713764,
            "alarm_code": 307
        },
        {
            "timestamp": 1663713764,
            "alarm_type": "Command syntax",
            "info": {
                "position": 31362
            }
        }
    ],
    "common_vars": {
        "1": 0,
        "2": 0.123,
        "3": 255,
        "4": 1.125
    },
    "feed_rate_override": 90,
    "active_tool": 7,
    "alerts": [
        "Machine took too long (3 seconds) to respond"
    ]
}

Running, no alarms, no variables reported

{
    "success": true,
    "part_count": 45,
    "cycle_state": "ACTIVE",
    "estopped": false,
    "program_name": "O456",
    "alarms": [],
    "common_vars": {},
    "feed_rate_override": null,
    "active_tool": null,
    "alerts": [
        "Machine is not reporting common variables"
    ]
}

Machine without alarm or variable reporting

{
    "success": true,
    "part_count": 7,
    "cycle_state": "RUNNING",
    "estopped": false,
    "program_name": "Default",
    "alerts": []
}