Introduction to Python

Python® is an interpreted, object-oriented, high-level programming language with dynamic semantics. Its high-level built in data structures, combined with dynamic typing and dynamic binding, make it very attractive for Rapid Application Development, as well as for use as a scripting or glue language to connect existing components together.
Python's simple, easy to learn syntax emphasizes readability and therefore reduces the cost of program maintenance. Python supports modules and packages, which encourages program modularity and code reuse. The Python interpreter and the extensive standard library are available in source or binary form without charge for all major platforms, and can be freely distributed.
For more detailed information about Python®, please refer to their website: www.python.org

Legal notice: "Python" is a registered trademark of the PSF. SerialTool is not affiliated with or sponsored by PSF. SerialTool uses Python as a compatible programming language to run scripts and requires an official version of Python to be installed on your PC.

Get started

To get started, you need to have Python3 installed on your system. For Windows and MacOS operating systems, you need to download it directly from the Python download area.

For Windows click here.

For MacOS click here.

Note for MacOS users: In the current version of SerialTool for MacOS, the Python 3.12 framework is already integrated to comply with Apple's requirements regarding code signing.
If you want to use a different version installed on your system, you can change the settings from the "Python Environment" menu.

For Linux, it will be sufficient to download and install it from the command line:

$> sudo apt-get install python3 python3-dev

to verify the installation:

$> python --version

This guide does not provide detailed information on how to install Python on your system as there are dozens of updated tutorials available on how to download and install Python.

This page is written in English only and will be maintained in English. If you find any errors, please report them to our support team at SerialTool.

SerialTool Python Library

The SerialTool library for Python is already integrated and available directly from the SerialTool software and does not need to be downloaded.
The only operation is to maintain the import among the libraries in your script. The SerialTool library for Python currently has two types of functions:

• Serial Commands functions - commands to communicate with the serial port

• GUI functions - functions to interact with the SerialTool GUI

The functions related to the GUI have the prefix "_gui" before the function name.

Important notes

Note 1: Let the main GUI breathe.
Remember to always use time.sleep(0.1) to allow SerialTool to process other messages. Otherwise, the GUI will completely freeze and be unable to handle any user actions, requiring you to force the application to exit from an external operating system command or action.

Note 2: Exit the script gently.
To stop the script and exit, it is not advisable to use the sys.exit() function as it would cause the total closure of SerialTool as Python is integrated.
If necessary to stop the script execution via source code, the SerialTool.stopscript function is provided.
If you find yourself inside a loop, it is possible to stop the execution via the [STOP] button directly from the GUI.

Serial Port Functions

The functions related to the serial port always refer to a serial port set up through the GUI in the serial ports panel. In the normal use of SerialTool, being software that manages multiple serial ports at the same time, it is necessary to assign your physical serial port to a serial port that SerialTool will take as a reference. This process is called "assignment".
If SerialTool is used in GUI mode only, the assignment can occur from the serial ports panel; if you do not intend to use the serial ports panel for assignment, or you intend to create a completely autonomous script, you can use the SerialTool.assignPort function explained later. Before operating with the serial port, it is therefore necessary to provide the assignment of the port name (in Windows COM and in MacOS/Linux the device name) to a number from 1 to the maximum of assignable ports (2 for the free version of SerialTool and 4 for the PRO version).

Once the serial port has been assigned to a serial, you can proceed with the command for opening. The opening is done through the SerialTool.open function, which can inherit the GUI settings by providing only the serial number (1-4) or opening it by setting parameters on the fly without needing the GUI settings, indeed, overriding them. Using the port opening with parameters, the script becomes completely independent from the graphical interface. To proceed to writing and reading, the write and read functions are documented below. It should be emphasized that the read function occurs automatically without the need for flush commands and without indicating the number of bytes you intend to read. The read function automatically returns all data read from the serial port and only stops with the timeout set after the reception of the last byte.

If for some reason your script has errors and the serial port remains open, it is necessary to close it before being able to use it again. For this reason, in the settings, it is possible and highly recommended that all open serial ports be automatically closed when exiting the script.
This setting is executed when exiting the script due to an error, when exiting without an error, and when exiting through the SerialTool.stopscript() function.

Below are described the functions available in this software release related to the serial port.

Function: SerialTool.init

input	return	Description
none	NULL	This function needs to be called before starting to use SerialTool functions. Usage: `SerialTool.init()`

Function: SerialTool.version

input	return	Description
none	(string)	This function returns the version of the SerialTool library. Usage: `SerialTool.version()`

Function: SerialTool.stopscript

input	return	Description
none	(int) 1 success (int) <0 Error type	To gracefully exit your script while keeping the SerialTool running, use the stopscript function instead of `sys.exit()` or similar Python functions will abruptly terminate the script and terminate SerialTool. The `SerialTool.stopscript()` function will automatically close the opened serial ports if "Automatically close serial ports when the script finishes execution" is enabled in the Script settings (settings menu). Usage: `SerialTool.stopscript()`

[Serial] Function: SerialTool.scan

input	return	Description
none	NULL	This function scans all ports and automatically unassigns and closes all previously assigned serial ports. Usage: `SerialTool.scan()`

[Serial] Function: SerialTool.list

input	return	Description
none	(int) 1 - Number of serial ports avalable (string) - Ports List	This function scans all ports and automatically unassigns and closes all previously assigned SerialPorts. Usage: `SerialTool.list()`

[Serial] Function: SerialTool.open {overloaded}

input	return	Description
(int) Assigned serial port (from GUI or manually)	(int) 1 Port opened (success) (int) <0 Error type	Open serial with parameters set in GUI. Usage: `assignedValue=1 SerialTool.open(assignedValue)`

[Serial] Function: SerialTool.open {overloaded}

input	return	Description
(int) Assigned serial port (from GUI or manually) (int) Baudrate (int) Bits values from 5 to 9 (string) Parity [N] none, [O]dd, [E]ven - for Windows and Linux [S]pace, [M]ark (float) Stop Bits 1, 1.5 or 2 (int) Byte to Byte timeout (use 50ms as default) (int) DTR start value 1=High 0=Low (int) RTS start value 1=High 0=Low (int) Flow control: Windows: 0 - None, 1 - Xon/Xoff, 2 - RTS/CTS, 3 - DSR/DTR Linux/MACOS: 0 - None, 1 - Xon/Xoff, 2 - RTS/CTS	(int) 1 Port opened (success) (int) <0 Error type	Open serial port with parameters. Usage: `assignedValue=1 result = SerialTool.open(assignedValue, 9600, 8, "N", 1, 50, 1, 1, 0)`

[Serial] Function: SerialTool.close

input	return	Description
(int) Assigned serial port (from GUI or manually)	(int) 1 Port closed (success) (int) <0 Error type	Close serial port. Usage: `assignedValue=1 SerialTool.close(assignedValue)`

[Serial] Function: SerialTool.write

input	return	Description
(int) Assigned serial port (from GUI or manually) (string) Buffer to send (write) (int) Buffer length in bytes	(int) n Buffer length (success) (int) <0 Error type	Write buffer to assigned serial port (send). Usage: `assignedValue=1 BufferToSend = "Hello World!\n" result = SerialTool.write(assignedValue, BufferToSend, len(BufferToSend))`

[Serial] Function: SerialTool.read

input	return	Description
(int) Assigned serial port (from GUI or manually)	(int) n > 0 Buffer read length (success), (bytes) read buffer (int) <0 Error type	Read buffer from assigned serial port (receive). Usage: `assignedValue=1 result = SerialTool.read(assignedValue) num_bytes, buffer_bytes = result`

[Serial] Function: SerialTool.setDTR

input	return	Description
(int) Assigned serial port (from GUI or manually)	(int) 1 success (int) <0 Error type	Set DTR line to High state. Usage: `assignedValue=1 result = SerialTool.setDTR(assignedValue)`

[Serial] Function: SerialTool.clearDTR

input	return	Description
(int) Assigned serial port (from GUI or manually)	(int) 1 success (int) <0 Error type	Clear DTR line (Low state). Usage: `assignedValue=1 result = SerialTool.clearDTR(assignedValue)`

[Serial] Function: SerialTool.setRTS

input	return	Description
(int) Assigned serial port (from GUI or manually)	(int) 1 success (int) <0 Error type	Set RTS line to High state. Usage: `assignedValue=1 result = SerialTool.setRTS(assignedValue)`

[Serial] Function: SerialTool.clearRTS

input	return	Description
(int) Assigned serial port (from GUI or manually)	(int) 1 success (int) <0 Error type	Clear RTS line (Low state). Usage: `assignedValue=1 result = SerialTool.clearRTS(assignedValue)`

GUI Functions

The GUI functions are used to interact directly with and through the graphical interface of SerialTool. The chosen functions up to this release of the SerialTool library for Python are designed to interact with the user without having to install additional libraries. If you already have your own code with other graphical libraries, you are still free to use it by importing it as a normal Python script.
The implemented functions relate to selecting the serial port (among those available), choosing files to load or save, and pop-up messages to ask the user to make choices or simply inform them of errors, warnings, or the end of the script execution.
Through the GUI-related functions, you must never forget that you are manipulating the main interface, and you must avoid causing freezes. For this reason, it is advisable to include sleep cycles that allow the main interface to continue running. Conceptually, when the [RUN] button of the script is pressed, it is launched in a thread of the main program. The GUI functions listed below are thread-safe, so no further precautions are needed at the code level to generate signals or anything else. You can simply use them as they are. Once invoked, the GUI functions interact with the user and require the user to make their choice before unlocking the Python script; the main interface in this case remains operational, and if there are readings or writings on the serial ports in progress, they are still managed.
For example, if you are sending or receiving bytes through SerialTool (from the main graphical interface) on the assigned serial port 1, and from your Python script you are operating on serial port 2 and request a confirmation message for a certain operation, serial port 1 will continue to be operational, receiving, sending, and displaying data. As explained previously, you only need to add a time.sleep(0.1) to avoid completely blocking the graphical interface in the Python script. In the examples available from SerialTool, this mechanism is well explained and is simple and intuitive.

Below are the GUI functions implemented up to the current software release.

[GUI] Function: SerialTool.gui_selectport

input	return	Description
none	(int) >= 0The selected serial port position in the list of available serial ports. (int) -1 if no port has been chosen by the user (Cancel button) (string) Selected Serial Port name	This function opens a dialog to let the user choose a serial port. Usage: `result = SerialTool.gui_selectport() while result == -1: time.sleep(0.1) SelectedPortPosition, SelectedPortName = result`

[GUI] Function: SerialTool.assignPort

input	return	Description
(string) Portname, (int) Port Number (1 to 4)	(int) = 1 Port assigned. (int) <0 Error type	This function assigns a serial number to a serial port, allowing you to access all SerialTool port operations such as open, close, read, write, etc. It is absolutely necessary if you intend to operate any of the SerialTool port functions and the port is not already assigned from the main GUI. In Windows use "COMx" while in MacOS and Linux use the device name "/path/of/your/device" Usage: Windows `SerialTool.assignPort("COM4", 1)` MacOS and Linux `SerialTool.assignPort("/dev/ttyUSB0", 1)`

[GUI] Function: SerialTool.insertPacket

input	return	Description
(int) Assigned serial port (from GUI or manually), (String) Packet Buffer to insert, (int) Packet Buffer Length, (int) Data Type: 1=Received 2=Sent	(int) = 1 - Packet inserted (int) <0 Error type	This function manually inserts a packet into a session's packet list. The data type argument should be 1 for RECEIVED packets and 2 for SENT packets. Remember that the serial port must be opened to use this function. Note: This function is automatically invoked when a `SerialTool.write` or `SerialTool.read` function is called. Use it only when strictly necessary. Usage: `assignedValue=1 result = SerialTool.insertPacket (assignedSerialPort, "ASCII String", 12, 1)`

[GUI] Function: SerialTool.gui_loadfile

l

input	return	Description
none	(int) >0 - File Length, (string) - Filename (int) <0 - Error type (string) - Error String	Opens a file dialog and enables the user to select a file for loading. This function returns the selected file name along with its length. However, it does not perform the actual loading of the file. Usage: `result = SerialTool.gui_loadfile () while result == -1: time.sleep(0.1) filesize, filename = result`

[GUI] Function: SerialTool.gui_savefile

input	return	Description
none	(int) 1 - Success, (string) - Filename (int) 0 - Error type, (string) - Error String	Opens a file dialog and enables the user to select a file for saving. This function returns the selected file name. However, it does not perform the actual saving of the file. Usage: `result = SerialTool.gui_savefile () while result == -1: time.sleep(0.1) filesize, filename = result`

[GUI] Function: SerialTool.gui_showmessage

input	return	Description
(String) Title - Message window's title (String) Message - Message to display to the user (int) Message Type - 1=Information, 2=Warning, 3=Critical, 4=Confirmation	(int) 0 - YES (Confirmation type only) (int) 1 - NO (Confirmation type only) (int) 2 - CANCEL (Confirmation type only) (int) 3 - OK (Information, Warning and Critial types only) (int) <0 Error type	This function displays a message and captures user responses. To capture the user's response, you need to implement a loop like this: `while result == -1:` `time.sleep(0.1)` This loop catches the message afterward; otherwise, you will lose the message when the user clicks. This may not be necessary if you simply want to display an information, warning or critical message. Usage: messageType = 4 result = SerialTool.gui_showmessage ("Confirmation Message", "This is a Confirmation message.\r\n\r\nApplication will be blocked until you click a button.", messageType) while result == -1: time.sleep(0.1) if messageType == 4: if (result == 0): resultText = "You pressed YES" print(f"Message Box result [YES] ({result})") elif (result == 1): resultText = "You pressed NO" print(f"Message Box result [NO] ({result})") elif (result == 2): resultText = "You pressed CANCEL" print(f"Message Box result [CANCEL] ({result})") elif (result == 3): resultText = "You pressed OK" print(f"Message Box result [OK] ({result})" # not available in Confirmation type)

Errors

This is the current list of errors implemented in the current version:

Error Code	Meaning
-1	Function called with a missing argument.
-2	(internal error) Error occurred while creating an integer answer.
-3	(internal error) Error occurred while creating a character answer.
-4	(internal error) Error occurred while creating a return answer.
-5	Bad input argument provided to the function.
-10	Serial port not assigned.
-11	Serial port not opened.
-12	Error in sending buffer.
-14	Serial port not found.
-15	Serial port already closed.
-16	Serial port already opened.
-17	Failed to close serial port.
-18	Failed to open serial port.
-19	Port already assigned.
-30	Wrong data type used.
-31	Wrong data length.