Script Library Tutorial

Original Instructions (EN)

Version 1.0
By Phillip Grambo | pgra@[Link]
The information contained herein is the property of Universal Robots A/S and shall not be reproduced in
whole or in part without prior written approval of Universal Robots A/S.

The information herein is subject to change without notice and should not be construed as a
commitment by Universal Robots A/S. This manual is periodically reviewed and revised.

Universal Robots A/S assumes no responsibility for any errors or omissions in this document.

Copyright © 2024 by Universal Robots A/S

The Universal Robots logo is a registered trademark of Universal Robots A/S.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
2
1 PURPOSE
URScript is the underlying code that makes the robot act. Users can create extensive additional
functionality by using URScript. This guide is a walkthrough of how to develop that functionality, and
examples of what can be made.

2 TABLE OF CONTENTS
1 Purpose ................................................................................................................................................. 3
3 What is this guide? ................................................................................................................................ 4
4 What is URScript? ................................................................................................................................. 5
5 URScript Manual ................................................................................................................................... 8
6 Tools for Writing URScript .................................................................................................................... 9
6.1 On the Teach Pendant .................................................................................................................. 9
6.2 URSim .......................................................................................................................................... 10
6.3 Notepad ...................................................................................................................................... 10
6.4 Notepad++ .................................................................................................................................. 11
6.5 VS Code ....................................................................................................................................... 12
6.6 Document Writers....................................................................................................................... 14
6.7 VNC.............................................................................................................................................. 14
6.8 FTP ............................................................................................................................................... 14
7 Making a Simple Function with def(): ................................................................................................. 16
8 Inserting a .script File Into a Before Start Sequence........................................................................... 17
9 Functions That Call Other Functions ................................................................................................... 25
10 TCP/IP Socket Communication Example ......................................................................................... 27
11 Global vs Local Variables ................................................................................................................. 29
12 Writing an Entire Program in URScript ........................................................................................... 32
13 Organizing and Managing Your Library ........................................................................................... 35
14 Change Log ...................................................................................................................................... 37

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
3
3 WHAT IS THIS GUIDE?
This guide is a walkthrough of how to make your own script library for a UR robot. A script library is a
collection of user defined functions that build upon the existing functions native to the environment.
These user-defined functions are useful for making reusable blocks of code to provide new, different, or
complicated functionality to the robot.

This guide is not a master reference for URScript programming in general. That document, called the UR
Script Manual, can be found on our website at: [Link]
e-series/script/script-manual-e-series-sw-512/.

This guide is also not a “What is programming?” instructional document. While this guide does offer a
brief description of what programming is, this is meant as a refresher. This guide assumes a rudimentary
knowledge of what programming is, and why you might program something.

 Background Concepts: What is programming?

 Programming is the act of making instructions for a computer to follow.
 Code is actual instructions for the computer.
 Code must be written in a Programming Language that the computer can read, like Python, C,
C++, Java, or URScript. Computers have to read these exact and explicit languages, because
human languages like English are too vague and imprecise for consistent results.
 Code is often written in a human-accessible software like PolyScope, and then Compiled into a
more detailed language like URScript, which the computer will then use.
 Computers will do exactly what you have told them to do, regardless of what you actually meant
for them to do.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
4
4 WHAT IS URSCRIPT?
URScript is a custom programming language developed by Universal Robots. It is similar to Python, but
not exactly the same. It does not have the entire capacity of Python, but it has added functionality
specific to our robot and controller. URScript files are saved with a .script file name.

When you press Play on the teach pendant, a .script file is compiled from the program file, installation
file, and any installed URCaps. The recently generated .script file, which has the same name as the .urp
file, will overwrite an existing .script file if it has the same name. The .script file will then be sent to the
controller, which executes the .script file, causing the robot to move and act as described in the program
file.

PolyScope is a GUI (Graphical User Interface) that users control to put premade program nodes
(Waypoints, Set nodes, If statements, URCap commands, etc.) in order. These nodes compile very
reliably into working .script files. Polyscope also allows users to insert script nodes into the program,
which will then contain either a single line or a file of URScript commands. This guide will walk you
through using and inserting you own .script files.

Figure 1: Diagram of .script File Creation when Play Button is Pressed. Note that the .script File is Not Compiled Until the
Program is Played, and Is Not Recompiled Until the Program is Changed and Played Again.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
5
Figure 2: A Simple Robot Program that Moves from Waypoint_1 to Waypoint_2, then waits for 5 seconds, in its Compiled
[Link] Format that Executes on the UR Controller. Lines 2-12 are from the .installation File. Program Node Text is
Shown as: $ LineNumber “Node Text”.

Figure 3: The PolyScope Program that was Compiled into the Script File in the Previous Image

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
6
Figure 4: Example program_name.script Contents from a URCap

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
7
5 URSCRIPT MANUAL
The Universal Robots script manual contains:

 The available variable types

 Flow of control
 How functions work
 Scoping rules
 How URScript interacts with the actual robot controller
 A listing of a known functions
 Other supporting information

The script manual can be downloaded at: [Link]

series/script/script-manual-e-series-sw-512/

It can also be read online at: [Link]

[Link]/manuals/content/SW_5_13/Documentation%20Menu/Script%20Manual

Have the URScript manual available while reading and using this guide. The manual is the master
reference for what URScript is and how it works. This guide builds on top of that manual, describing a
particular use case for URScript.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
8
6 TOOLS FOR WRITING URSCRIPT
A .script file can be written and edited in any text editor. A .script file is just a text file that has been
saved with a .script file name.

6.1 ON THE TEACH PENDANT

The Script node insertion can be found on under the Advanced group of nodes. From here, you can type
out individual lines, or use the “file” option. In the file editor, you can open existing .script files, or write
them from scratch. This is useful for viewing and debugging files on a real robot in the field, but large
writing and programming tasks on a touchscreen keyboard is rarely preferred over any other option.

You can plug a USB keyboard into the USB ports on the teach pendant or in the controller to make
things easier. However, you may need to change the keyboard to match your locality. USB keyboards
will be mapped as Danish layout by default. Letters and numbers will likely be correct, but some special
characters may be incorrect. The guide linked below explains how to change the keyboard mapping of
USB keyboards.

[Link]
layout/

Figure 5: Script Node Insertion in PolyScope

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
9
Figure 6: Script File Editor Screen

6.2 URSIM
The offline URSim offers the same programming interface as the teach pendant. Other than being on
your computer, it is no different. However, you do have a keyboard and mouse built in, making things
easier. Also, you can easily transfer script files from the simulator to repositories, flash drives, emails,
and file folder locations, which is very helpful during development and project management tasks.

6.3 NOTEPAD
Basic text editors like Notepad can be used, and most people already have Notepad or a similar software
already installed. It lacks several features, like line numbers and color formatting, so it typically is used
to inspect and read .script files, but not write or edit them.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
10
Figure 7: Example URScript Code in Notepad

6.4 NOTEPAD++
Notepad++ is a popular free text editor that has some features useful for writing .script files. It can show
line numbers, and format by programming language. Setting the language to Python (URScript is most
similar to Python) makes for a decent URScript IDE.

[Link]

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
11
Figure 8: Setting Notepad++ to Python

Figure 9: A .script File Notepad++ with Python Set as the Language

6.5 VS CODE
VS Code is a free software IDE from Microsoft. It can be downloaded at [Link]
What sets VS Code above the other options is the community developed extension for URScript:
Universal Robots A/S Phone +45 8993 8989
Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
12
[Link] This extension provides
formatting help, function autocompletion, syntax help, and information about function arguments for
known functions in the script manual.

Figure 10: URScript Extension for VS Code

Figure 11: Autocomplete Example for VS Code URScript Extension

Because this extension is developed outside of UR, we cannot guarantee that it is kept up to date.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
13
6.6 DOCUMENT WRITERS
It is possible, but not recommended, to write .script files in a document writing software like MS Word,
as these typically try to auto-format and spell-check text to human languages like English, as opposed to
a programming language.

6.7 VNC
Before discussing the capabilities of VNC, safety information and disclaimers must be addressed first.
Using a VNC connection to our robots violates Single Point of Control, therefore it should not be used in
production. It can be used for development and troubleshooting purposes if appropriate precautions are
taken. Single Point of Control is a machine safety principle, stating that there can only ever be one
method of turning on a machine at any given time. This is crucial for lock-out/tag-out and other safety
procedures.

VNC (Virtual Network Computing) is a way of remotely accessing and controlling one computer from
another computer. Our robots are run from a computer, so they can be controlled in this manner from a
separate computer. Remoting into a robot from across the room or building can be extremely useful for
quick edits.

To use VNC, you have to install a VNC server on the robot. The community developed magic file for this
is linked below. When you are done using VNC on your robot, it is recommended to either uninstall the
server, or disable remote access to the robot in the security settings.

[Link]

6.8 FTP
While FTP is not a writing tool, it is a very useful way to transfer script files from a computer to the
robot. The typical workflow for moving files to and from a robot is a flash drive, but FTP allows you to
transfer files over an ethernet cable. FTP (File Transfer Protocol) is a way of accessing a computer’s file
system remotely. To use FTP, you will need software that can act as an FTP Client. UR typically suggests
FileZilla ([Link]) as a free FTP Client. To connect to the robot, you will need the following
parameters:

 Host: IP address of the robot

 Username: root
 Password: easybot
 Port: 22

When using FTP, be aware that by inputting a root password, there are no read/write restrictions. If you
edit anything outside of the Programs folder, you will likely negatively affect the robot.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
14
Figure 12: FileZilla Client Connecting a PC to a UR Robot

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
15
7 MAKING A SIMPLE FUNCTION WITH DEF():
User defined functions are declared with the def(): command. All functions must be concluded with end.
Within the parentheses of the def(): declaration, comma separated arguments can be passed into the
function. Arguments can have default values assigned to them. The parentheses must be followed by a
colon. A user defined function can optionally return values. Within the script function, any existing script
functions from the script manual or other previously defined user functions can be used. Once a
function has been defined, it can be called from within the file, or anywhere else in the PolyScope
program.

Figure 13: Example .script Function

For a simple example of a user-defined script function that doesn’t return a value, let’s make a function
that turns off the digital outputs 4 through 7. This function could be used upon program start to reset all
the outputs connected to a stack light. We will define a function following the structure of the previous
figure, and within the program we will use the function set_digital_out() from the URScript manual.

Figure 14: A User Defined .script Function That Turns Off Outputs 4 Through 7

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
16
8 INSERTING A .SCRIPT FILE INTO A BEFORE START SEQUENCE
Now that a .script file has been written, it needs to be inserted into robot program so it can be used.

First, it must be transferred from where it was written, onto the robot. Copy and Paste via a flash drive is
likely the easiest. FTP software like FileZilla can also work well.

Figure 15: The .script File in a Windows File Folder

Figure 16: The .script File in the Polyscope File Navigator

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
17
Now that the .script file has been pasted onto the robot, it needs to be inserted into the program. For
this example, it will be loaded into the before start sequence. To do this, in PolyScope, begin by inserting
a script node into the program from the Advanced program node list. Select the File option from the
drop-down menu in the upper right. Click on the Edit option to load a new file. Click on Open in the
upper left, and then select your .script file. Press Exit once it has loaded onto the screen.

Figure 17: The File Option Location in a Script Node in PolyScope

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
18
Figure 18: The Script Node with File Selected

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
19
Figure 19: The Script File Editor Screen

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
20
Figure 20: Select the Desired .script File

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
21
Figure 21: The .script File Loaded into the File Editor

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
22
Figure 22: The .script File that has been Successfully Inserted into PolyScope

Now that the .script file has been inserted into the before start sequence, it is ready to be called. To do
so, at the desired point in your code, insert a script line node, and type out the name of user defined
function. Use the parentheses, and input arguments if appropriate (they are not used in this example),
but do not use the colon.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
23
Figure 23: Calling the User Defined Function

Congratulations! You have written a user defined function in a text editor, transferred it to your robot,
inserted the function definition, and called the function in the program!

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
24
9 FUNCTIONS THAT CALL OTHER FUNCTIONS
The next step in the example is a set of script functions that will be used to control a stack light. In this
example, each output controls a selected color. The user will call script functions that turn off all the
lights and turn on the desired color. All of these script functions will be written in one file.

To set the stack light to Green, a function will be defined named stack_light_green(). This function will
call the previous user defined function stack_light_off(), and then the manual defined function
set_digital_out(). This process is then repeated for each color.

Figure 24: The File Containing all the User Defined Functions to Operate the Stack Light

This file is inserted into PolyScope the same was as before.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
25
Figure 25: The Stack Light Controller File Inserted into PolyScope and its contained Functions Called

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
26
10TCP/IP SOCKET COMMUNICATION EXAMPLE
A common use of script functions is Socket TCP/IP communications. Individually, each command is a
script function. They can be tedious to replicate and use frequently, especially if several commands must
be used as a group. An example of this grouping is the series of commands needed to trigger a Cognex
barcode camera. The camera needs to receive the specific text “||>TRIGGER ON” (without the
quotations), and then a carriage return and line feed command to execute the text command. After a
short time, the camera again needs to receive the same command set, but with OFF instead of ON.
Carriage Return and Line Feed are ASCII bytes 13 and 10, respectively. These 7 lines of code can be
replaced with a single function, as shown below:

Figure 26: A User Defined Function Called top_scan() That Has a Default Scan Time of 1 Second

As a similar example, let’s consider opening a socket. Opening a socket is a single line of script code, if
everything works as intended. In reality, auxiliary devices may need multiple connection attempts if they
are slow to boot, and your program may need specific behavior if the sockets fail to open. A
comprehensive socket connection function, like the one shown below, can handle retries and failure
behavior in a neat package. This function can be used to open each of your sockets, and be used in all of
your programs.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
27
Figure 27: A User Defined Function Called myCamOpenFunction() That Has a Retry Manager and a Connection Failure Manager
Built In

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
28
11GLOBAL VS LOCAL VARIABLES
An important concept in making script libraries is the scoping of variables. Scoping refers to the domain
of existence and validity of variables, or rather, where they can be used. In a computer program with
libraries and references and dependencies, its easy it unknowingly use a variable name that is already in
the program somewhere else. Variable names are typically chosen for legibility to the author and future
users, and often multiple authors are unaware of the variables selected by each other. Common variable
names like “x,” “index,” “user_input,” and “loop_count” are likely legitimate and intuitive selections in
multiple separate instances. However, without proper scope control, its possible to inadvertently
overwrite the same variable in its other use instances.

Global variables are accessible from anywhere in the robot program, encompassing the main program
file as well as any script functions that have been defined and added to the to program. Local variables,
by contrast, exist at their originating level. The same variable name can be used as a local variable in a
function, and as a global variable in the layer above. These two instances of the variable are separate
entities, despite sharing a name. This prevents a user from accidentally overwriting a variable that is
used elsewhere in a library.

It is best practice to make all variables in supporting libraries local variables, particularly if the program
author is not the library author. The exception is variables that may be useful or necessary to for the
program author to access or monitor. For these global variables that originate from within a script
function, it is recommended to use a clear and consistent naming convention that the program author
would not naturally select. An example naming convention for global variables created within a script
function could be: “COMPANYNAME_LIBRARYNAME_VARIABLENAME”.

If a variable is created in a function without explicitly being declared as local or global, it will default to
global.

Figure 28: Scoping Diagram Illustrating Where the Example Variables my_var and test_var are Accessible
Universal Robots A/S Phone +45 8993 8989
Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
29
Figure 29: Example Code Where the Variable my_var is Local to Several Functions

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
30
Figure 30: The Example Code from the Previous Image, Running in PolyScope

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
31
12 WRITING AN ENTIRE PROGRAM IN URSCRIPT
You can write an entire robot program in URScript code. This is rare and typically unadvised, as
PolyScope is exceptionally user friendly for handling most things a robot will do. However, as a
conceptual exercise, it interesting to see. The program executes and runs, moving the robot to
waypoints and updating the stack light at each waypoint. While this program could certainly be done
with PolyScope program nodes, it illustrates what can be done with URScript.

Figure 31: The First Half of the URScript File that Runs an Entire Robot Program

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
32
Figure 32: The Second Half of the URScript File that Runs an Entire Robot Program

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
33
Figure 33: The PolyScope Program that Runs from Two Script Node: One to Define Everything, and One to Call the Main
Program.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
34
13ORGANIZING AND MANAGING YOUR LIBRARY
Once you have made a few functions, it is important to keep track of them. Treat your code as a
revision-controlled engineering document, with authors, version numbers, and change logs. If a function
has changed to the point that a call to the original function wouldn’t work on the current version, you
now have a new non-interchangeable function that must use a different name.

Figure 34: A URScript Function with Revision Control Comments

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
35
As your libraries expand, consider using repositories with check-in/check-out and restore-to-previous-
version capabilities. GitHub is a popular option for this.

To take backups from a robot, consider using our Magic File for backups ([Link]
[Link]/download/software-e-series/support/magic-files/magic-file-backup-all-programs/) for
convenience. Plug it into your robot, and it will create a zip folder with all your programs on the flash
drive. The name of the zip folder will have the serial number of the robot, as well as the date and time
stamp of the backup. Keep these backups, and have read-only master copies.

Part of managing a library is testing and verification of the functions. It should be noted that some errors
are only found at runtime when the functions are called upon. Some errors, like a missing “end”
statement to wrap a user-defined function, will be caught immediately when the program is played.
However, if you accidentally spell a function name wrong or use the wrong variable type (ex: attempt to
movel() to a list instead of a pose), these errors will not be identified until program execution reaches
that point. As such, it is best practice to call your functions in a test environment to ensure functionality,
and not merely confirm that PolyScope can compile the resultant file.

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
36
14CHANGE LOG
Version Date Author Contact Comments
1.0 1/29/2024 PGRA pgra@[Link] Initial release

Universal Robots A/S Phone +45 8993 8989

Energivej 25 Fax +45 3879 8989
DK-5260 Odense S info@[Link]
CVR-nr. 29 13 80 60 [Link]
37