TCP Socket API for MachineMotion

Overview

This document details the commands that can be sent to your MachineMotion AI using Ethernet TCP/IP protocol. It is supported on MachineMotion software version v3.1.0 and newer versions. This API uses sockets to exchange data. All information is packaged in string format and sent over the socket communication channel to port 9999 of the MachineMotion AI.

The TCP Socket API is a TCP server that enables a TCP client to :

Get information about the status of the MachineMotion
Get information and send commands to motors connected to the MachineMotion
Set outputs and read inputs of the IO modules connected to the MachineMotion
Send and receive custom messages over the mqtt broker of the MachineMotion

For details on previous releases of Vention’s Low-Level Socket Programming Interface with MachineMotion 2 and MachineMotion 1, refer to the ‘Documentation for Previous Releases’ section at the end of this document.
Documentation for Previous Product Versions

Configuring an IP Address

See MachineMotion AI Controller User Manual to learn more about how to configure the IP address of the MachineMotion.

A connection must be opened before any commands can be sent or received from the MachineMotion. How to open a connection will depend on the programming language being used.

Commands Reference

Get Safety State

Description

Returns the safety state of the MachineMotion.

Format

getSafetyState

Usage

getSafetyState

Response

The safety state of the MachineMotion can be one of those values:

-1 corresponds to an error in the safety state
0 corresponds to no safety state (this would be the case for the MachineMotion AI Robot and MachineMotion AI Robot Pro models)
1 corresponds to an emergency stop state
2 corresponds to a normal safety state
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Operational State

Description

Returns the operational state of the MachineMotion.

Format

getOperationalState

Usage

getOperationalState

Response

The operational state of the MachineMotion can be one of those values:

1 corresponds to operational
0 corresponds to non-operational
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Enable Operation

Description

Request the MachineMotion to change its operational state to be operational again.

Format

operationEnable

Usage

operationEnable

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Disable Operation

Description

Request the MachineMotion to change its operational state to not be operational.

Format

operationDisable

Usage

operationDisable

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Move

Description

Moves an axis immediately, to a given position, distance or speed.

Format

move_<Payload>;*

Where <Payload>> corresponds to a TrapezoidalMove or a ContinuousMove .

Note : ;* means multiple can be input in the same request.

Trapezoidal Move

Moves an axis immediately to a given position or by a given distance.

Fields can be specified in any order.

Field	Description	Is Mandatory
`type:trapezoidal`	The move type	yes
`relative:[0,1]`	Is the motion relative or absolute	yes
`[port:<int>,index:<int>,target:<float>]`	The motor address (port and index) and its target position for absolute moves, or its target distance for relative moves. One move can have multiple of this field, in order to move multiple motors.	yes
`velocity:<float>`	Desired velocity, in mm/sec	yes
`acceleration:<float>`	Desired acceleration, in mm/sec2	yes
`deceleration:<float>`	NOT USED (Desired deceleration)	no
`jerk:<float>`	NOT USED (Jerk value of the move)	no
`ignoreSync:[0,1]`	Ignore the synchronization configuration of parent and child motors	no

Continuous Move

Moves a conveyor or rotary table axis continuously at a given speed and acceleration.

Fields can be specified in any order.

Field	Description	Is Mandatory
`type:continuous`	The move type	yes
`port:<int>`	The motor address (port)	yes
`index:<int>`	The motor address (index)	yes
`velocity:<float>`	Desired velocity, in mm/sec. Positive numbers correspond to moving in the positive direction of the axis. Negative numbers correspond to moving in the negative direction of the axis.	yes
`acceleration:<float>`	Desired acceleration, in mm/sec2	yes

Usage

move_type:trapezoidal,[port:1,index:1,target:300],velocity:300,acceleration:100,relative:1 starts moving the first motor connected to port 1, by a distance of 300 mm, with a velocity of 300 mm/sec, and an acceleration of 100 mm/sec2.

move_type:continuous,port:1,index:1,velocity:300,acceleration:100 starts moving the first motor connected to port 1, continuously at a velocity of 300 mm/sec, with an acceleration of 100 mm/sec2.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Add Move

Description

Adds a move to list of moves, to be executed later, when the command moveGo will be sent.

It will enable moving an axis to a given position, distance or speed, later on.

Format

moveAdd<Payload>;*

Where <Payload> corresponds to a TrapezoidalMove or a ContinuousMove .

Note : ;* means multiple can be input in the same request.

Trapezoidal Move

Moves an axis to a given position or by a given distance.

Fields can be specified in any order.

Field	Description	Is Mandatory
`type:trapezoidal`	The move type	yes
`relative:[0,1]`	Is the motion relative or absolute	yes
`[port:<int>,index:<int>,target:<float>]`	The motor address (port and index) and its target position for absolute moves, or its target distance for relative moves. One move can have multiple of this field, in order to move multiple motors.	yes
`velocity:<float>`	Desired velocity, in mm/sec	yes
`acceleration:<float>`	Desired acceleration, in mm/sec2	yes
`deceleration:<float>`	NOT USED (Desired deceleration)	no
`jerk:<float>`	NOT USED (Jerk value of the move)	no
`ignoreSync:[0,1]`	Ignore the synchronization configuration of parent and child motors	no

Continuous Move

Moves a conveyor or rotary table axis continuously at a given speed and acceleration.

Fields can be specified in any order.

Field	Description	Is Mandatory
`type:continuous`	The move type	yes
`port:<int>`	The motor address (port)	yes
`index:<int>`	The motor address (index)	yes
`velocity:<float>`	Desired velocity, in mm/sec	yes
`acceleration:<float>`	Desired acceleration, in mm/sec2	yes

Usage

moveAdd_type:trapezoidal,[port:1,index:1,target:300],velocity:300,acceleration:100,relative:1 will queue up a motion that starts moving the first motor connected to port 1, by a distance of 300 mm, with a velocity of 300 mm/sec, and an acceleration of 100 mm/sec2.

moveGo will start executing the previously described move.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Go Move

Description

Will start the execution of all the moves that have been queued up by the moveAdd command.

Format

moveGo

Usage

moveGo will start executing the previously described move.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Clear Move

Description

Will clear all the moves that have been queued up by the moveAdd command, without executing them.

Format

moveClear

Usage

moveClear will start clear the previously described move. It will not be executed by any subsequent moveGo command.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Move Home

Description

Moves an axis immediately, towards its home position, until the home sensor is triggered. This will reset the zero position of the axis.

Format

moveHome_<Payload>;*

Where <Payload>> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Note : ;* means multiple can be input in the same request.

Usage

moveHome_1,1 starts moving the first motor connected to port 1, towards its home sensor.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Add Move Home

Description

Adds a homing move to list of homing moves, to be executed later, when the command moveHomeGo will be sent.

It will enable moving an axis towards its home position, until the home sensor is triggered. This will reset the zero position of the axis.

Format

moveHomeAdd_<Payload>;*

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Note : ;* means multiple can be input in the same request.

Usage

moveHomeAdd_1,1;2_1 will queue up a motion that will start moving the first motor connected to port 1, as well as the first motor connected to port 2, towards their home sensors.

moveHomeGo will start executing the previously described move.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Go Move Home

Description

Will start the execution of all the moves that have been queued up by the moveHomeAdd command.

Format

moveHomeGo

Usage

moveHomeAdd_1,1;2_1 will queue up a motion that will start moving the first motor connected to port 1, as well as the first motor connected to port 2, towards their home sensors.

moveHomeGo will start executing the previously described move.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Clear Move Home

Description

Will clear all the moves that have been queued up by the moveHomeAdd command, without executing them.

Format

moveHomeClear

Usage

moveHomeAdd_1,1;2_1 will queue up a motion that will start moving the first motor connected to port 1, as well as the first motor connected to port 2, towards their home sensors.

moveHomeClear will start clear the previously described move. It will not be executed by any subsequent moveHomeGo command.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Quick Stop

Description

Immediately stops motion on the given axes.

Format

quickStop_<Payload>;*

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Note : ;* means multiple can be input in the same request.

Usage

quickStop_1,1;2,2 will immediate stop any motion on the first motor connected to port 1, and the second motor connected to port 2.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Set Position

Description

Sets the current position of an axis to a new value. It does not move the axis.

Format

setPosition_<Payload>

Where <Payload> corresponds to <port>, <index>,<position> :

<port> is the motor address (port)
<index> is the motor address (index)
<position> is the new position value, in mm.

Usage

setPosition_1,1,1000 Sets the current position if the first motor connected to port 1 at position 1000 mm.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Set Ignore End Sensors

Description

Sets whether or not the axis should ignore the status of its end of travel sensors during a move.

Format

setIgnoreEndSensor_<Payload>

Where <Payload> corresponds to <port>, <index>,<[0,1]> :

<port> is the motor address (port)
<index> is the motor address (index)
<[0,1]> 1 corresponds to ignoring them, 0 corresponds to take them into account. By default, they won’t be ignored.

Usage

setIgnoreEndSensor_1,1,0 Sets the the first motor connected to port 1 to not ignore its end of travel sensors.

Response

1 corresponds to a success
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Connected

Description

Queries the connection status of a motor: whether or not it is currently detected as available hardware by the MachineMotion.

Format

getConnected_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getConnected_1,2 returns whether or not there is a motor detected on port 1, in second position in the motor chain.

Response

1 corresponds to a motor being detected at the given address
0 corresponds to no motor being detected at the given address
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Position

Description

Queries the current position of a motor.

Format

getPosition_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getPosition_1,1 returns the position of the first motor connected to port 1.

Response

A real number corresponding to the position of the axis, in millimetres. For example, 1237.222 .
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Velocity

Description

Queries the current speed of a motor.

Format

getVelocity_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getVelocity_1,1 returns the speed of the first motor connected to port 1.

Response

A real number corresponding to the speed of the axis, in mm/sec. For example, 400.12 .
Positive numbers correspond to moving in the positive direction of the axis.
Negative numbers correspond to moving in the negative direction of the axis.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Target Reached

Description

Queries whether or not a motor has yet reached its target.

A motor is considered to have reached its target if any of these are satisfied:

it has reached its specified position or velocity for trapezoidal and continuous moves respectively
it has triggered one of its end of travel sensors
it has been interrupted by a quick stop command.

Format

getTargetReached_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getTargetReached_1,1 returns whether the first motor connected to port 1 has reached its target or not.

Response

0 corresponds to the target not yet being reached.
1 corresponds to the target having been reached.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Motion Allowed

Description

Queries whether or not a motor is ready to accept new motion commands.

Generally, motion is allowed when target is reached or when operation is disabled.

Format

getMotionAllowed_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getMotionAllowed_1,1 returns whether the first motor connected to port 1 is ready to accept new motion commands or not.

Response

0 corresponds to the motor not being ready to accept new motion commands.
1 corresponds to the motor being ready to accept new motion commands.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Brake Status

Description

Queries whether or not the brake is locked on a given motor.

Format

getBrakeStatus_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getBrakeStatus_1,1 returns whether the first motor connected to port 1 has its brake locked or not.

Response

0 corresponds to the brake being unlocked.
1 corresponds to the brake being locked.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Home Sensor

Description

Queries whether or not the home sensor of a given motor is triggered.

Format

getHomeSensor_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getHomeSensor_2,2 returns whether the second motor connected to port 2 has its home sensor triggered or not.

Response

0 corresponds to the home sensor not being triggered.
1 corresponds to the home sensor being triggered.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get End Sensor

Description

Queries whether or not the endstop sensor of a given motor is triggered.

Format

getEndSensor_<Payload>

Where <Payload> corresponds to <port>, <index> :

<port> is the motor address (port)
<index> is the motor address (index)

Usage

getEndSensor_2,1 returns whether the first motor connected to port 2 has its endstop sensor triggered or not.

Response

0 corresponds to the endstop sensor not being triggered.
1 corresponds to the endstop sensor being triggered.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Digital Input

Description

Reads a digital input from a Digital IO Module or a Push Button Module.

Format

getDigitalInput_<Payload>

Where <Payload> corresponds to <port>, <module> :

<port> is the module’s address (port it is connected to)
<module> is the module’s address (device ID)
<input> is the input pin number to read on the module. This is an optional parameter.

Usage

getDigitalInput_1,2,0 returns the current value of the input pin 0 from the module having the device ID 2, connected to the Control port 1.

getDigitalInput_1,2 returns the current value of all the input pins of the module having the device ID 2, connected to the Control port 1.

Response

A pin can have a value of 0 or 1 .
The value of all the pins of the module will be represented as a byte. For example, 15 corresponds to 0b1111 , meaning that all 4 input pins of the module currently have a value of 1 .
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get Digital Output

Description

Reads a digital output from a Digital IO Module or a Power Switch Module.

Format

getDigitalOutput_<Payload>

Where <Payload> corresponds to <port>, <module> :

<port> is the module’s address (port it is connected to)
<module> is the module’s address (device ID)
<output> is the output pin number to read on the module. This is an optional parameter.

Usage

getDigitalOutput_1,2,0 returns the current value of the output pin 0 from the module having the device ID 2, connected to the Control port 1.

getDigitalOutput_1,2 returns the current value of all the output pins of the module having the device ID 2, connected to the Control port 1.

Response

A pin can have a value of 0 or 1 .
The value of all the pins of the module will be represented as a byte. For example, 15 corresponds to 0b1111 , meaning that all 4 output pins of the module currently have a value of 1 .
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Set Digital Output

Description

Writes a digital output from a Digital IO Module or a Power Switch Module.

Format

setDigitalOutput_<Payload>

Where <Payload> corresponds to <port>, <module> :

<port> is the module’s address (port it is connected to)
<module> is the module’s address (device ID)
<output> is the output pin number to write on the module
<value> is the value to write to the pin

Usage

setDigitalOutput_1,2,0,1 writes the value 1 to the output pin 0 of the module having the device ID 2, connected to the Control port 1.

Response

1 corresponds to a success
0 corresponds to a failure
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get User Input

Description

Reads a the value of a retained mqtt topic on the MachineMotion corresponding to a custom user input.

Format

getUserInput_<inputName>

Where <inputName> corresponds to the mqtt topic name.

Usage

getUserInput_CUSTOMINPUT returns the retained message of the mqtt topic tsapi/userInput/CUSTOMINPUT .

Response

A String corresponding to retained message on the given mqtt topic.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Get User Output

Description

Reads a the value of a retained mqtt topic on the MachineMotion corresponding to a custom user output.

Format

getUserOutput_<outputName>

Where <outputName> corresponds to the mqtt topic name.

Usage

getUserOutput_CUSTOMOUTPUT returns the retained message of the mqtt topic tsapi/userOutput/CUSTOMOUTPUT .

Response

A String corresponding to retained message on the given mqtt topic.
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

Set User Output

Description

Writes a the value of a retained mqtt topic on the MachineMotion corresponding to a custom user output.

Format

setUserOutput_<outputName>,<outputValue>

Where:

<outputName> corresponds to the mqtt topic name
<outputValue> corresponds to the mqtt message

Usage

setUserOutput_CUSTOMOUTPUT,CUSTOMMESSAGE writes the retained message CUSTOMMESSAGE on the mqtt topic tsapi/userOutput/CUSTOMOUTPUT .

Response

1 corresponds to a success
0 corresponds to a failure
ERROR <#> corresponds to a failure, where <#> will be the number corresponding to the error.

List of error numbers

Error Number	Error Description
2	Motion server not found
3	Bad request
4	Cannot read value
5	Bad input value
6	Input value is out of range
7	Motor not connected
8	Missing input value
98	Endpoint not found
99	Unknown error

Documentation for Previous Releases

Application Programming Interface: Low-Level Sockets for MachineMotion V2

Application Programming Interface: Low-Level Sockets for MachineMotion V2 SW V2.0

Application Programming Interface: Low-Level Sockets for MachineMotion V2 SW V2.3

Application Programming Interface: Low-Level Sockets for MachineMotion V1

Application Programming Interface: Low-Level Sockets V1 User Manual