Machine update format

This format is used for updating machines manually and by the proxy to send machine updates (in the state field of proxy socket messages).

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 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).

`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": []
}

Machine update format

Fields

success

part_count

cycle_state

estopped

program_name

alarms