Skip to content

Utilities

This page contains information on all functions present within util.py and aims to give a clear understanding both of what these functions do and the requirements for any data to be input into them.

Most of these functions contain actions for the arm that do not necessarily fit into other categories such as connection and checking verification.

Functions

arm_utilities

Source code in actions\util.py 
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
class arm_utilities():
    def __init__(self, arm:XArmAPI):
        self.arm = arm

    def connect(self, port=None, baudrate=None, timeout=None, axis=None, **kwargs):
        """
        Connect to arm

        Args:
            port: port name or ip address, default is the value when initializing an instance

            baudrate: baudrate, only available in serial, default is the value when initializing an instance

            timeout: timeout, only available in serial, default is the value when initializing an instance

            axis: number of axes, only required when using a serial port connection, default is 7
        """
        self.arm.connect(port=port, baudrate=baudrate, timeout=timeout, axis=axis, **kwargs)

    def disconnect(self):
        """
        Disconnect
        """
        self.arm.disconnect()

    def set_servo_attach(self, servo_id=None):
        """
        Attach the servo

        Args: 
            servo_id: 1-(Number of axes), 8, if servo_id is 8, will attach all servo

                1. 1-(Number of axes): attach only one joint

                    ex: arm.set_servo_attach(servo_id=1)

                2: 8: attach all joints

                    ex: arm.set_servo_attach(servo_id=8)

        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm.set_servo_attach(servo_id=servo_id)

    def set_servo_detach(self, servo_id=None):
        """
        Detaches the servo, be sure to do protective work before unlocking to avoid injury or damage.

        Args:
            servo_id: 1-(Number of axes), 8, if servo_id is 8, will detach all servo

                1. 1-(Number of axes): detach only one joint

                    ex: arm.set_servo_detach(servo_id=1)

                2: 8: detach all joints, please

                    ex: arm.set_servo_detach(servo_id=8)
        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm.set_servo_detach(servo_id=servo_id)

    def clean_warn(self):
        """
        Clean the warn

        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm.clean_warn()

    def clean_conf(self):
        """
        Clean current config and restore system default settings

        Note:
            1. This interface will clear the current settings and restore to the system default settings

        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm.clean_conf()

    def save_conf(self):
        """
        Save config

        Note:
            1. This interface can record the current settings and will not be lost after the restart.
            2. The clean_conf interface can restore system default settings

        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm.save_conf()

    def check_verification(self):
        """
        checks verification

        Returns:
            out (tuple[int, int]): tuple((code, status)), returned result is only corrent when code is 0.

            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.

            status (int):
                0: verified
                other: not verified
        """
        return self.arm.check_verification()

    def system_control(self, value=1):
        """
        Control the xArm controller system

        Args:
            value:
                1: shutdown
                2: reboot

        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm.system_control(value=value)

    def set_reduced_mode(self, on):
        """
        Turn on/off reduced mode

        Note:
            1. This interface relies on Firmware 1.2.0 or above

        Args:
            on: True/False
                such as: Turn on the reduced mode : code=arm.set_reduced_mode(True)

        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm.set_reduced_mode(on)

    def reset(self, speed=None, mvacc=None, mvtime=None, is_radian=None, wait=False, timeout=None):
        """
        Reset the xArm

        Warning:
            without limit detection

        Note:
            1. If there are errors or warnings, this interface will clear the warnings and errors.
            2. If not ready, the api will auto enable motion and set state
            3. This interface does not modify the value of last_used_angles/last_used_joint_speed/last_used_joint_acc

        Args:
            speed: reset speed (unit: rad/s if is_radian is True else °/s), default is 50 °/s

            mvacc: reset acceleration (unit: rad/s^2 if is_radian is True else °/s^2), default is 5000 °/s^2

            mvtime: reserved

            is_radian: if the speed and acceleration are in radians or not, defaults to self.default_is_radian

            wait: whether to wait for the arm to complete, default is False

            timeout: maximum waiting time(unit: second), default is None(no timeout), only valid if wait is True
        """
        return self.arm.reset(speed=speed, mvacc=mvacc, mvtime=mvtime, is_radian=is_radian, wait=wait, timeout=timeout)

    def emergency_stop(self):
        """
        Emergency stop (set_state(4) -> motion_enable(True) -> set_state(0))

        Note:
            1. This interface does not automatically clear errors. If there is an error, you will need to handle it according to the error code.
        """
        return self.arm.emergency_stop()

    def run_blockly_app(self, path, **kwargs):
        """
        Run the app generated by xArmStudio software

        Args:
            path: app path
        """
        return self.arm.run_blockly_app(path, **kwargs)

    def run_gcode_file(self, path, **kwargs):
        """
        Run the gcode file

        Args:
            path: gcode file path
        """
        return self.arm.run_gcode_file(path, **kwargs)

    def delete_blockly_app(self, name):
        """
        Delete blockly app

        ArgsP:
            name: blockly app name

        Returns:
            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
        """
        return self.arm._studio.delete_blockly_app(name)   

    def send_hex_cmd(self, datas, **kwargs):
        """
        Hexadecimal communication protocol instruction

        Args:
            datas: Hexadecimal data_list

            timeout: timeout: wait timeout, seconds, default is 10s.

        Returns: 
            out: Hexadecimal data_list or code

            code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
                Note: code 129~144 means modbus tcp exception, the actual modbus tcp exception code is (code-0x80), refer to [Standard Modbus TCP](./UF_ModbusTCP_Manual.md)
        """
        return self.arm.send_hex_cmd(datas, **kwargs)

    def run_gcode_app(self, path, **kwargs):
        """
        Run gcode project file by xArmStudio software

        Args:
            path: gcode file path

        Returns: 
            code (int): returned result is only corrent when code is 0.
        """
        return self.arm.run_gcode_app(path, **kwargs)

check_verification()

checks verification

Returns:

Name Type Description
out tuple[int, int]

tuple((code, status)), returned result is only corrent when code is 0.
code int

See the API Code Documentation for details.
status int

0: verified other: not verified
Source code in actions\util.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def check_verification(self):
    """
    checks verification

    Returns:
        out (tuple[int, int]): tuple((code, status)), returned result is only corrent when code is 0.

        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.

        status (int):
            0: verified
            other: not verified
    """
    return self.arm.check_verification()

clean_conf()

Clean current config and restore system default settings

Note
  1. This interface will clear the current settings and restore to the system default settings

Returns:

Name Type Description
code int

See the API Code Documentation for details.
Source code in actions\util.py 
76
77
78
79
80
81
82
83
84
85
86
def clean_conf(self):
    """
    Clean current config and restore system default settings

    Note:
        1. This interface will clear the current settings and restore to the system default settings

    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm.clean_conf()

clean_warn()

Clean the warn

Returns:

Name Type Description
code int

See the API Code Documentation for details.
Source code in actions\util.py 
67
68
69
70
71
72
73
74
def clean_warn(self):
    """
    Clean the warn

    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm.clean_warn()

connect(port=None, baudrate=None, timeout=None, axis=None, **kwargs)

Connect to arm

Parameters:

Name Type Description Default
port

port name or ip address, default is the value when initializing an instance

 None
baudrate

baudrate, only available in serial, default is the value when initializing an instance

 None
timeout

timeout, only available in serial, default is the value when initializing an instance

 None
axis

number of axes, only required when using a serial port connection, default is 7

 None
Source code in actions\util.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
def connect(self, port=None, baudrate=None, timeout=None, axis=None, **kwargs):
    """
    Connect to arm

    Args:
        port: port name or ip address, default is the value when initializing an instance

        baudrate: baudrate, only available in serial, default is the value when initializing an instance

        timeout: timeout, only available in serial, default is the value when initializing an instance

        axis: number of axes, only required when using a serial port connection, default is 7
    """
    self.arm.connect(port=port, baudrate=baudrate, timeout=timeout, axis=axis, **kwargs)

delete_blockly_app(name)

Delete blockly app

ArgsP

name: blockly app name

Returns:

Name Type Description
code int

See the API Code Documentation for details.
Source code in actions\util.py 
200
201
202
203
204
205
206
207
208
209
210
def delete_blockly_app(self, name):
    """
    Delete blockly app

    ArgsP:
        name: blockly app name

    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm._studio.delete_blockly_app(name)

disconnect()

Disconnect

Source code in actions\util.py 
22
23
24
25
26
def disconnect(self):
    """
    Disconnect
    """
    self.arm.disconnect()

emergency_stop()

Emergency stop (set_state(4) -> motion_enable(True) -> set_state(0))

Note
  1. This interface does not automatically clear errors. If there is an error, you will need to handle it according to the error code.
Source code in actions\util.py 
173
174
175
176
177
178
179
180
def emergency_stop(self):
    """
    Emergency stop (set_state(4) -> motion_enable(True) -> set_state(0))

    Note:
        1. This interface does not automatically clear errors. If there is an error, you will need to handle it according to the error code.
    """
    return self.arm.emergency_stop()

reset(speed=None, mvacc=None, mvtime=None, is_radian=None, wait=False, timeout=None)

Reset the xArm

Warning

without limit detection

Note
  1. If there are errors or warnings, this interface will clear the warnings and errors.
  2. If not ready, the api will auto enable motion and set state
  3. This interface does not modify the value of last_used_angles/last_used_joint_speed/last_used_joint_acc

Parameters:

Name Type Description Default
speed

reset speed (unit: rad/s if is_radian is True else °/s), default is 50 °/s

 None
mvacc

reset acceleration (unit: rad/s^2 if is_radian is True else °/s^2), default is 5000 °/s^2

 None
mvtime

reserved

 None
is_radian

if the speed and acceleration are in radians or not, defaults to self.default_is_radian

 None
wait

whether to wait for the arm to complete, default is False

 False
timeout

maximum waiting time(unit: second), default is None(no timeout), only valid if wait is True

 None
Source code in actions\util.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
def reset(self, speed=None, mvacc=None, mvtime=None, is_radian=None, wait=False, timeout=None):
    """
    Reset the xArm

    Warning:
        without limit detection

    Note:
        1. If there are errors or warnings, this interface will clear the warnings and errors.
        2. If not ready, the api will auto enable motion and set state
        3. This interface does not modify the value of last_used_angles/last_used_joint_speed/last_used_joint_acc

    Args:
        speed: reset speed (unit: rad/s if is_radian is True else °/s), default is 50 °/s

        mvacc: reset acceleration (unit: rad/s^2 if is_radian is True else °/s^2), default is 5000 °/s^2

        mvtime: reserved

        is_radian: if the speed and acceleration are in radians or not, defaults to self.default_is_radian

        wait: whether to wait for the arm to complete, default is False

        timeout: maximum waiting time(unit: second), default is None(no timeout), only valid if wait is True
    """
    return self.arm.reset(speed=speed, mvacc=mvacc, mvtime=mvtime, is_radian=is_radian, wait=wait, timeout=timeout)

run_blockly_app(path, **kwargs)

Run the app generated by xArmStudio software

Parameters:

Name Type Description Default
path

app path

 required
Source code in actions\util.py 
182
183
184
185
186
187
188
189
def run_blockly_app(self, path, **kwargs):
    """
    Run the app generated by xArmStudio software

    Args:
        path: app path
    """
    return self.arm.run_blockly_app(path, **kwargs)

run_gcode_app(path, **kwargs)

Run gcode project file by xArmStudio software

Parameters:

Name Type Description Default
path

gcode file path

 required

Returns:

Name Type Description
code int

returned result is only corrent when code is 0.
Source code in actions\util.py 
229
230
231
232
233
234
235
236
237
238
239
def run_gcode_app(self, path, **kwargs):
    """
    Run gcode project file by xArmStudio software

    Args:
        path: gcode file path

    Returns: 
        code (int): returned result is only corrent when code is 0.
    """
    return self.arm.run_gcode_app(path, **kwargs)

run_gcode_file(path, **kwargs)

Run the gcode file

Parameters:

Name Type Description Default
path

gcode file path

 required
Source code in actions\util.py 
191
192
193
194
195
196
197
198
def run_gcode_file(self, path, **kwargs):
    """
    Run the gcode file

    Args:
        path: gcode file path
    """
    return self.arm.run_gcode_file(path, **kwargs)

save_conf()

Save config

Note
  1. This interface can record the current settings and will not be lost after the restart.
  2. The clean_conf interface can restore system default settings

Returns:

Name Type Description
code int

See the API Code Documentation for details.
Source code in actions\util.py 
88
89
90
91
92
93
94
95
96
97
98
99
def save_conf(self):
    """
    Save config

    Note:
        1. This interface can record the current settings and will not be lost after the restart.
        2. The clean_conf interface can restore system default settings

    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm.save_conf()

send_hex_cmd(datas, **kwargs)

Hexadecimal communication protocol instruction

Parameters:

Name Type Description Default
datas

Hexadecimal data_list

 required
timeout

timeout: wait timeout, seconds, default is 10s.

 required

Returns:

Name Type Description
out

Hexadecimal data_list or code
code int

See the API Code Documentation for details. Note: code 129~144 means modbus tcp exception, the actual modbus tcp exception code is (code-0x80), refer to Standard Modbus TCP
Source code in actions\util.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def send_hex_cmd(self, datas, **kwargs):
    """
    Hexadecimal communication protocol instruction

    Args:
        datas: Hexadecimal data_list

        timeout: timeout: wait timeout, seconds, default is 10s.

    Returns: 
        out: Hexadecimal data_list or code

        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
            Note: code 129~144 means modbus tcp exception, the actual modbus tcp exception code is (code-0x80), refer to [Standard Modbus TCP](./UF_ModbusTCP_Manual.md)
    """
    return self.arm.send_hex_cmd(datas, **kwargs)

set_reduced_mode(on)

Turn on/off reduced mode

Note
  1. This interface relies on Firmware 1.2.0 or above

Parameters:

Name Type Description Default
on

True/False such as: Turn on the reduced mode : code=arm.set_reduced_mode(True)

 required

Returns:

Name Type Description
code int

See the API Code Documentation for details.
Source code in actions\util.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def set_reduced_mode(self, on):
    """
    Turn on/off reduced mode

    Note:
        1. This interface relies on Firmware 1.2.0 or above

    Args:
        on: True/False
            such as: Turn on the reduced mode : code=arm.set_reduced_mode(True)

    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm.set_reduced_mode(on)

set_servo_attach(servo_id=None)

Attach the servo

Parameters:

Name Type Description Default
servo_id

1-(Number of axes), 8, if servo_id is 8, will attach all servo

  1. 1-(Number of axes): attach only one joint

    ex: arm.set_servo_attach(servo_id=1)

2: 8: attach all joints

ex: arm.set_servo_attach(servo_id=8)
None

Returns:

Name Type Description
code int

See the API Code Documentation for details.
Source code in actions\util.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def set_servo_attach(self, servo_id=None):
    """
    Attach the servo

    Args: 
        servo_id: 1-(Number of axes), 8, if servo_id is 8, will attach all servo

            1. 1-(Number of axes): attach only one joint

                ex: arm.set_servo_attach(servo_id=1)

            2: 8: attach all joints

                ex: arm.set_servo_attach(servo_id=8)

    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm.set_servo_attach(servo_id=servo_id)

set_servo_detach(servo_id=None)

Detaches the servo, be sure to do protective work before unlocking to avoid injury or damage.

Parameters:

Name Type Description Default
servo_id

1-(Number of axes), 8, if servo_id is 8, will detach all servo

  1. 1-(Number of axes): detach only one joint

    ex: arm.set_servo_detach(servo_id=1)

2: 8: detach all joints, please

ex: arm.set_servo_detach(servo_id=8)
None

Returns: code (int): See the API Code Documentation for details.

Source code in actions\util.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def set_servo_detach(self, servo_id=None):
    """
    Detaches the servo, be sure to do protective work before unlocking to avoid injury or damage.

    Args:
        servo_id: 1-(Number of axes), 8, if servo_id is 8, will detach all servo

            1. 1-(Number of axes): detach only one joint

                ex: arm.set_servo_detach(servo_id=1)

            2: 8: detach all joints, please

                ex: arm.set_servo_detach(servo_id=8)
    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm.set_servo_detach(servo_id=servo_id)

system_control(value=1)

Control the xArm controller system

Parameters:

Name Type Description Default
value

1: shutdown 2: reboot

 1

Returns:

Name Type Description
code int

See the API Code Documentation for details.
Source code in actions\util.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
def system_control(self, value=1):
    """
    Control the xArm controller system

    Args:
        value:
            1: shutdown
            2: reboot

    Returns:
        code (int): See the [API Code Documentation](./xarm_api_code.md#api-code) for details.
    """
    return self.arm.system_control(value=value)