Yaskawa Robot Communication SDK for Python

UnderAutomation.Yaskawa is a Python package that communicates with Yaskawa Motoman robot controllers (YRC1000 (micro), MOTOMAN NEXT, DX100 / DX200, FS100, ERC / XRC / MRC) through the High Speed Ethernet Server (HSES) of the controller, over UDP, and through the Ethernet Server (TCP), the web server (HTTP) and the FTP server of the controller. Nothing is installed on the controller.

Use it to read the status, the alarms and the positions, move the robot, select and start jobs, read and write variables and I/O, transfer files, and compute the forward and inverse kinematics of 169 robot models, from a Python script.

• Product page: underautomation.com/yaskawa
• Documentation: underautomation.com/yaskawa/documentation/get-started-python
• Also available for .NET: Yaskawa.NET, and LabVIEW: Yaskawa.vi.

How it works

The package wraps the .NET library UnderAutomation.Yaskawa.dll with pythonnet. The DLL is inside the package: pip install installs everything, including pythonnet.

• Windows: the DLL runs on the .NET Framework 4.x of Windows. Nothing else to install.

• Linux and macOS: install the .NET runtime (for example .NET 8), then tell pythonnet to use it before you start Python:

  sudo apt-get install -y dotnet-runtime-8.0   # Ubuntu, for example
  export PYTHONNET_RUNTIME=coreclr

  Without this variable, pythonnet uses Mono, its default runtime on Linux and macOS. You can also choose the runtime in your code, before the first import of the package:

  from pythonnet import load
  load("coreclr")

Installation

Python 3.7 to 3.13 is supported (the limit of pythonnet 3.0.5). Install the package in a virtual environment:

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux and macOS
source .venv/bin/activate

pip install UnderAutomation.Yaskawa

Or install it from the sources of this repository:

git clone https://github.com/underautomation/Yaskawa.py.git
cd Yaskawa.py
pip install -e .

Getting started

from underautomation.yaskawa.yaskawa_robot import YaskawaRobot
from underautomation.yaskawa.connect_parameters import ConnectParameters

# The SDK runs in trial mode for 30 days. Register your key to remove the trial limit.
# YaskawaRobot.register_license("Your Company", "your-license-key")

robot = YaskawaRobot()
robot.connect(ConnectParameters("192.168.0.1"))

status = robot.high_speed_e_server.get_status_information()
print("Servo on:", status.servo_on, "Alarm:", status.alarming)

robot.disconnect()

ConnectParameters also gives the ping before the connection (ping_before_connect, True by default), and the ports and timeouts of the High Speed Ethernet Server (high_speed_e_server.data_port, high_speed_e_server.data_timeout_milliseconds...).

Protocol	Property of YaskawaRobot	Port	Enabled by default
High Speed Ethernet Server	high_speed_e_server	UDP 10040 and 10041	Yes
Ethernet Server	e_server	TCP 80	No
HTTP	http	TCP 80	No
FTP	ftp	TCP 21	No

Enable the other protocols with parameters.e_server.enable = True, parameters.http.enable = True and parameters.ftp.enable = True.

From .NET names to Python names

The Python API is the .NET API with Python names. The .NET documentation applies to Python.

.NET	Python
Method GetStatusInformation()	get_status_information()
Property HighSpeedEServer	high_speed_e_server
Static method YaskawaRobot.RegisterLicense(...)	YaskawaRobot.register_license(...)
Enum value AlarmResetType.Reset	AlarmResetType.Reset (an IntEnum)
Array short[]	list-like object, use list(...) to copy it
Nullable<int>	int | None

Each type is in the module named after it, in snake case: UnderAutomation.Yaskawa.HighSpeedEServer.AlarmResetType is underautomation.yaskawa.high_speed_e_server.alarm_reset_type.AlarmResetType.

Features

The sections below use the High Speed Ethernet Server, through robot.high_speed_e_server. The other protocols and the kinematics follow.

Status and alarms

from underautomation.yaskawa.high_speed_e_server.robot_recent_alarm import RobotRecentAlarm
from underautomation.yaskawa.high_speed_e_server.alarm_reset_type import AlarmResetType

status = robot.high_speed_e_server.get_status_information()
print(status.teach, status.play, status.running)

alarm = robot.high_speed_e_server.get_alarm(RobotRecentAlarm.Latest)
print(alarm.code, alarm.text, alarm.occurring_time)

robot.high_speed_e_server.alarm_reset(AlarmResetType.Reset)

Positions

position = robot.high_speed_e_server.get_robot_cartesian_position()
print(position.x, position.y, position.z, position.rx, position.ry, position.rz)

joints = robot.high_speed_e_server.get_robot_joint_position()
print(list(joints.axes))  # pulses of each axis

Motion

The robot must be in remote mode, see "Configure the robot" below.

from underautomation.yaskawa.high_speed_e_server.position_command_classification import PositionCommandClassification
from underautomation.yaskawa.high_speed_e_server.position_command_operation_coordinate import PositionCommandOperationCoordinate

robot.high_speed_e_server.set_servo(True)

# Cartesian move: mm and degrees, speed in mm/s, in the robot coordinate system
robot.high_speed_e_server.move_cartesian(
    1000, 10, 0, 0, 0, 0,
    PositionCommandClassification.Cartesian_MM_S, 10,
    PositionCommandOperationCoordinate.Robot)

# Joint move: pulses of each axis, speed in % of the maximum speed
robot.high_speed_e_server.move_joints([1000, 0, 0, 0, 0, 0], PositionCommandClassification.LinkPercent, 10)

Jobs

robot.high_speed_e_server.select_job("PROGRAM", 0)
robot.high_speed_e_server.start_job()

job = robot.high_speed_e_server.get_executing_job_information()
print(job.name, job.line, job.step)

Variables

registers = robot.high_speed_e_server.read_register(0, 5)
print(list(registers.value))

robot.high_speed_e_server.write_register(0, [100, 200])

reals = robot.high_speed_e_server.read_real(0, 4)
strings = robot.high_speed_e_server.read16_bytes_char(0, 2)
positions = robot.high_speed_e_server.read_position_variable(1, 4)

Files

files = robot.high_speed_e_server.get_file_list("*.JBI").files
print(list(files))

content = robot.high_speed_e_server.get_file("PROGRAM.JBI").content

Ethernet Server

parameters = ConnectParameters("192.168.0.1")
parameters.e_server.enable = True
robot.connect(parameters)

status = robot.e_server.get_status_information()
alarms = robot.e_server.get_alarm_with_messages()
tcp = robot.e_server.get_robot_cartesian_position()

robot.e_server.select_job("PICK", 0)
robot.e_server.set_servo(True)
robot.e_server.start_job()
completed = robot.e_server.wait_for_job_completion(60)  # blocks until the end of the job, 60 s at most

FTP

The anonymous account (default) can only download: use ftp to upload and delete.

parameters = ConnectParameters("192.168.0.1")
parameters.ftp.enable = True
parameters.ftp.ftp_user = "ftp"
robot.connect(parameters)

for item in robot.ftp.get_listing("/JOB"):
    print(item.name, item.modified)

robot.ftp.download_files_to_local(["/JOB/TEST.JBI", "/DAT/VAR.DAT"], "backup")

# The controller does not overwrite a job by FTP: delete it first
if robot.ftp.file_exists("/JOB/PICK.JBI"):
    robot.ftp.delete_file("PICK.JBI")
robot.ftp.upload_file_from_local("PICK.JBI", None, lambda percent: print(f"{percent:.0f} %"))

HTTP

from underautomation.yaskawa.common.file_extension import FileExtension

for file in robot.http.get_file_list(FileExtension.DAT):
    print(file.name, file.description)

job = robot.http.get_file("TEST.JBI")

Offline kinematics

from underautomation.yaskawa.common.dh_parameters import DhParameters
from underautomation.yaskawa.common.joints_angles import JointsAngles
from underautomation.yaskawa.common.cartesian_position import CartesianPosition
from underautomation.yaskawa.kinematics.arm_kinematic_models import ArmKinematicModels
from underautomation.yaskawa.kinematics.kinematics_utils import KinematicsUtils

dh = DhParameters.from_arm_kinematic_model(ArmKinematicModels.GP7)  # or DhParameters.from_prm_file("ALL.PRM")

# Joint angles in degrees (S, L, U, R, B, T) to flange position in mm and degrees
flange = KinematicsUtils.forward_kinematics(JointsAngles(0, 0, 0, 0, -90, 0), dh)

# Every joint solution for a flange position: up to 8, or 16 for the HC10 cobots
solutions = KinematicsUtils.inverse_kinematics(CartesianPosition(400, 100, 300, 180, 0, 0), dh)

Examples

The folder examples contains scripts ready to run. The first run asks the IP address of the robot and saves it in examples/robot_config.json (ignored by git). The shared helper examples/__init__.py sets the Python path, manages this file and registers the license.

Run a script from the root of the repository, or browse them with the launcher:

python examples/high_speed_e_server/hses_get_status.py
python examples/launcher.py

Script	What it does
hses_get_status.py	Status of the controller: mode, servo, alarm, hold.
hses_get_cartesian_position.py	Cartesian position (X, Y, Z, Rx, Ry, Rz).
hses_get_joint_position.py	Joint position, in pulses.
hses_read_alarms.py	Last alarms with their code, type and text.
hses_alarm_reset.py	Resets the alarm or cancels the error.
hses_get_executing_job.py	Name, line and speed override of the executing job.
hses_select_start_job.py	Selects a job by name and starts it.
hses_read_write_registers.py	Reads and writes registers.
hses_read_write_integers.py	Reads and writes integer variables.
hses_read_write_reals.py	Reads and writes real variables.
hses_read_write_bytes.py	Reads and writes byte variables.
hses_read_write_strings.py	Reads and writes string variables (16 and 32 bytes).
hses_read_write_io.py	Reads and writes I/O signals (general, external, network).
hses_read_write_position_variables.py	Reads and writes position variables.
hses_move_cartesian.py	Moves the robot to a Cartesian position.
hses_move_joints.py	Moves the robot to joint pulse values.
hses_servo_command.py	Servo on and off.
hses_display_message.py	Shows a message on the pendant.
hses_get_system_info.py	Software version and name of the system.
hses_position_error_torque.py	Position error and torque of each axis.
hses_file_operations.py	Lists, downloads, uploads and deletes files.
eserver_get_status.py	Ethernet Server: status, error and alarms with their text.
eserver_get_positions.py	Ethernet Server: joints, Cartesian position in two frames, posture, torque, encoder temperatures.
eserver_job_list.py	Ethernet Server: job list with a filter, executing job.
eserver_read_write_variables.py	Ethernet Server: reads the B, I, D, R, S variables, writes a B variable.
eserver_read_write_io.py	Ethernet Server: reads signals, writes a network input byte.
eserver_run_job.py	Ethernet Server: selects and starts a job, waits for its end.
ftp_list_files.py	FTP: folders and files of the controller.
ftp_download_files.py	FTP: downloads the files of a pattern into a local folder.
ftp_upload_job.py	FTP: sends a job of the PC, replaces the existing job.
http_list_files.py	HTTP: files of each type with their description.
http_read_file.py	HTTP: reads a file and saves it on the PC.
kinematics_forward_inverse.py	Forward and inverse kinematics of a model of the catalog, offline.
kinematics_from_robot.py	DH parameters read from ALL.PRM, joint solutions of the current position.
license_info_example.py	State of the license, and registration of a key.

The motion examples and eserver_run_job.py move the robot. Check the surroundings of the robot first.

Configure the robot

The read functions work in any mode. The commands (servo, motion, job start, file write) need these settings on the controller, with the security mode set to MANAGEMENT. The website shows them with screenshots.

• Ethernet function: start the controller in maintenance mode (hold MAIN MENU at power on), then SYSTEM > SETUP > OPTION FUNCTION > NETWORK FUNCTION SETTING: set ETHERNET to USED, FTP and ETHERNET SERVER to EXPANDED. The IP address is in LAN INTERFACE SETTING.
• Parameters: RS000 = 2, RS005 = 1, RS007 = 2, RS022 = 1, RS029 = 1. Keep the timers RS034 and RS035 at 200 ms, their factory value. To write the I/O and the variables in play mode: S2C409 = 1 on DX100 and FS100, S2C541 = 0 and S2C542 = 0 on DX200, YRC1000 and YRC1000micro.
• Remote commands: IN/OUT > PSEUDO INPUT SIGNAL, select #82015 CMD REMOTE SEL with INTER LOCK + SELECT.
• Key in the remote position: the commands need the key of the pendant in the remote position. With the ladder editor, copy #80011 to #40042.
• Job selection: SETUP > FUNCTION ENABLE, set JOB SELECT WHEN REMOTE AND PLAY to PERMIT.
• File overwrite: PARAMETER > RS, set RS029 to 1 and RS214 to 1.

Compatibility

• Python: 3.7 to 3.13, with pythonnet 3.0.5.
• Operating systems: Windows (.NET Framework), Linux and macOS (.NET runtime and export PYTHONNET_RUNTIME=coreclr).
• Controllers: Yaskawa YRC1000 (micro), MOTOMAN NEXT, DX100 / DX200, FS100, ERC / XRC / MRC, with the High Speed Ethernet Server.

License

This SDK needs a commercial license. A 30-day trial starts at the first use, no key needed. After the trial, register your key in your code:

from underautomation.yaskawa.yaskawa_robot import YaskawaRobot

license_info = YaskawaRobot.register_license("Your Company", "your-license-key")
print(license_info.state)

• License agreement: underautomation.com/yaskawa/eula and License.md
• Trial key: underautomation.com/license
• Prices and quote: underautomation.com/yaskawa

Support

• Documentation: underautomation.com/yaskawa/documentation
• Issues: GitHub Issues
• Contact: underautomation.com/contact