Ohara Lab

Ohara Lab | Software

en ja

Ohara Lab / ohara-lab-su (github) / ohara-lab-su (docs) / ohara-lab (PyPI)

At Ohara Lab, we develop a range of tools used in research and experiments, with a particular focus on software for experimental equipment control and laboratory automation.

For experimental equipment control, the basic building block is a DeviceClass that does not depend on any particular framework or communication protocol. A DeviceClass can be used independently. Only when network access is required do we add a communication frame appropriate to the application, such as BL774-compatible REST / FastAPI, gRPC, or TANGO. Our fundamental approach is to preserve and reuse device-specific control software as far as possible, even when communication methods or higher-level systems change.

Update history

HISTORY

Device Servers and Device Classes

Below, we introduce the control programs (DeviceClasses) for individual devices and the device servers (DeviceServers) that use communication frames.

Communication Frames and Shared Functionality

others

Installation and Usage

Start with the DeviceClass package for the instrument you want to use. Packages distributed through PyPI can be installed with pip install <device-package>; pip resolves the declared dependencies. There is no requirement to install the entire system or every communication Frame in advance.

A DeviceClass can be used directly from Python. For network access, use a communication method supported by that particular DeviceClass (such as ese774, gRPC, or TANGO) and the device-server startup script provided with its package. Supported methods and bundled scripts vary by package.

For existing DeviceClasses, consult each package’s documentation. The technical discussion of developing a device server is covered under “DeviceClass and Device Server Development”.

DeviceClass and Device Server Development

A DeviceClass implements instrument control independently of the communication mechanism. A device server exposes that functionality over a network. Development separates instrument-control code from the communication Frame. For installation of existing packages, see Installation and Usage.

The detailed design, implementation, client interfaces, type handling, and operational constraints are documented in the following articles.

What Is SUSANOO?

return

Shimane University refers to its family of measurement systems, built around the DeviceClass as the basic unit, as SUSANOO, an acronym for Sustainable Unified Systems Architecture for Networked Operations and Orchestration (*). Although it provides a BL774-compatible (ese774) communication Frame for use at SPring-8, DeviceClass itself is independent of any particular framework or communication protocol. Its underlying philosophy is loose coupling at the device level, enabling measurement, analysis, visualization, decision-making, and related functions to be handled together.

(*) The name may change. Far too many projects in Shimane Prefecture already use the name Susanoo.

Overview of SUSANOO

return

SUSANOO does not aim to build a new full-stack protocol and framework like MADOCA/DARUMA at SPring-8 or TANGO at ESRF.

Its fundamental unit is the DeviceClass, which is independent of any particular framework or communication protocol. Device-specific control logic is separated out and maintained as a DeviceClass. Only when network access is needed is a communication Frame—such as BL774-compatible REST/FastAPI, gRPC, or TANGO—attached according to the intended application. The priority is not to replace existing control infrastructure, including TANGO, but to make it possible to reuse device-control assets with as little reimplementation as possible even when communication methods or higher-level systems change.

The necessary DeviceClasses and analysis functions are then loosely coupled as device objects, combining measurement, analysis, visualization, decision-making, and other functions.

Of course, organizing a system around device servers is also common in MADOCA and TANGO. SUSANOO, however, does not set out to design another large-scale framework, shared infrastructure, or protocol of that kind. Instead, it emphasizes the benefits of combining device servers and analysis functions implemented as microservices as needed.

SUSANOO also makes it easy to pair a target device with a communication speed and framework suited to the purpose, while keeping the way it is used essentially unchanged when the Frame is switched. In other words, the basic architecture is a simple transparent proxy.

At the same time, SUSANOO positions itself as BL774-compatible. Specifically, it is officially based on the BL774 REST server code and follows the conventions for GET and POST used by BL774 (although this compatibility remains incomplete). More importantly, there are still no substantial specifications or mechanisms for management or the API set. It therefore does not implement the 774 API set and falls short even of the 774 Basic System.

User-level management and access controls are deliberately not implemented. Even at its largest, the intended deployment scale is a single SPring-8 beamline (BL). The assumed environment is a laboratory’s collection of instruments and a rather rough-and-ready set of users with unrestricted access.

As a basic design choice, rather than having the framework standardize and organize APIs, SUSANOO leaves API specifications to the control classes. That is, its Frame is built around dynamic dispatch through a transparent proxy, so the Python API of a control class becomes the client-side API directly. Where APIs need to be standardized, that standardization is performed in the control classes.

This is because the system was designed from the outset on the assumption that the number of device servers would grow, and the fundamental APIs differ from device to device. Rather than focusing on devices such as motors, for which a common API set is already well established, it places greater importance on the ease of supporting a wide variety of devices. Put another way, it is designed with an uncompromisingly minimalist approach.

What Is a Transparent Proxy?

return

In SUSANOO, device access is implemented using a transparent proxy.

A proxy is a program that sits between a client and the actual device and mediates communication. SUSANOO, however, aims to do more than simply relay communications: it emphasizes preserving the original device class as much as possible. This allows users to operate a device much as they would a local Python object, with little need to be conscious of the network.

SUSANOO itself does not define new device-specific APIs or add complicated abstraction layers. Essentially, it simply exposes the methods of a device-control class so they can be called from the client. Consequently:

Of course, for APIs that should be shared across multiple manufacturers—for example, in robot control—the interfaces can be organized at the control-class level. That responsibility, however, belongs to each device library, not to the framework. The distinguishing feature of SUSANOO’s transparent-proxy architecture is thus that it provides a common communication mechanism while retaining as much of the original device-class functionality as possible (*).

(*) To begin with, transparent architectures that let users handle remote instruments much like local objects are widely used in instrument-control frameworks, including BL774. The relationship and terminology of Device, Device Class, and Device Server are also common, although SUSANOO’s particular classification and naming are strongly influenced by TANGO.

What Is Dynamic Dispatch?

return

SUSANOO uses dynamic dispatch to invoke device-control-class methods over a network.

For example, if a device-control class has the methods

device.move(...)
device.stop()
device.get_position()

then the client can call them in almost exactly the same way:

device.move(...)
device.stop()
device.get_position()

Internally, the process is:

client.move (...)
        ↓
network
        ↓
server
        ↓
device.move (...)

The server locates and executes the corresponding device-class method based on the method name and arguments sent by the client. With a conventional Web API, a separate API endpoint must be defined for each operation, such as move, stop, or get_position. Dynamic dispatch allows the methods of a control class to be exposed relatively directly, substantially reducing the amount of communication-layer code required when adding new instruments or functionality.

This is one of the fundamental mechanisms used to implement SUSANOO’s transparent proxy. The idea is to use the Python API of a control class as the network-accessible API, preserving it as directly as possible.

Initially, SUSANOO used Pydantic/OpenAPI to define API interfaces explicitly. In practice, however, even though the control classes already had Python APIs, the same interfaces also had to be defined and maintained on the communication side. This became cumbersome as more and more different devices were added. For this reason, fully dynamic dispatch, with the DeviceClass Python API serving directly as the interface, is now the default.

On the other hand, dynamic dispatch alone makes it difficult for external users to discover the available methods and interface details, such as argument types. Explicit API definitions using Pydantic/OpenAPI have therefore been retained and can be selected when an OpenAPI-based interface is needed.

For more details about the mechanism and its relationship to Pydantic/OpenAPI, see Dynamic Dispatch and API Definitions.

Robot Control

return

Robot-control device servers are a particularly important part of automation in SUSANOO (provisional name). Robot manufacturers naturally invest considerable effort in their own frameworks and control systems. SUSANOO is not intended to replace them. Because robots from different manufacturers serve different hardware purposes, their interfaces vary substantially. SUSANOO brings these interfaces into a somewhat unified API interface: in other words, it provides a loose abstraction of the manufacturers’ APIs. An API set spanning manufacturers is something a university is particularly well placed to design, rather than an individual manufacturer. The goal is to make it easy for experimenters to substitute one manufacturer’s robot for another despite their differences.

DENSO WAVE COBOTTA

return

In DENSO WAVE robots, the Motion Generator / Robot Motion inside the controller performs the actual motion control. Control interfaces such as PacScript, ORiN2, and b-CAP are provided above this layer.

Ordinary robot programs created using the teach pendant (TP) or WINCAPS run on the controller as PacScript, DENSO WAVE’s proprietary robot language. Alternatively, a PC can control the robot through ORiN2, or access the controller more directly at a lower level using b-CAP.

ORiN2 is a framework for treating various devices, including robots, as common objects, connecting to each device through a Provider. Because communication with the RC8 uses b-CAP underneath, ORiN2 provides higher-level device abstraction, whereas b-CAP is the communication protocol for accessing the controller.

Universal Robots

return

Universal Robots robots consist of a Robot Arm, Control Box, and Teach Pendant. The Control Box is the central component responsible for coordinating the joints, while PolyScope on the TP provides a higher-level environment for operation, teaching, and programming. Robot programs created in PolyScope and URScript sent from an external PC are ultimately executed by URControl in the Control Box and translated into robot motion.

Universal Robots provides several official interfaces for communication with an external PC, including RTDE, the Primary / Secondary Interface, and the Dashboard Server. Of these, RTDE is an official interface for bidirectional reading and writing of controller status, I/O, general-purpose registers, and related data between an external PC and the UR controller. However, RTDE itself does not define robot motion commands such as movej or movel. The robot program on the controller side is responsible, when necessary, for deciding how values passed through RTDE are used for motion.

The RTDEControlInterface currently used by SUSANOO is not an official Universal Robots API. It is an API provided by ur_rtde, an open-source library developed by SDU Robotics. It combines Universal Robots’ official RTDE with control URScript running on the robot, making functions such as moveJ, moveL, and servoJ callable from a PC. Universal Robots’ official RTDE and SDU Robotics’ ur_rtde must therefore be clearly distinguished.

The current implementation uses SDU Robotics’ RTDEControlInterface for motion control, RTDEReceiveInterface for status acquisition, RTDEIOInterface for I/O, the Dashboard Server for controller management, and the Primary Interface for obtaining controller messages and errors.

JAKA

return

In JAKA collaborative robots, the Robot Arm and Controller perform the actual motion control. Above these are the JAKA App for teaching and operation, robot programs executed on the Controller, and official SDKs / communication interfaces for external PCs. Official SDKs for C/C++, C#, and Python are available for external PC control, and gRPC is recommended for the V3 Controller. Meanwhile, the TCP/IP external-control protocol is also published, making it possible to implement custom controller status acquisition and control.

The official GitHub repositories also provide SDKs and ROS / ROS2 resources. However, the Python SDK uses jkrc and manufacturer-provided native libraries. The existence of public GitHub repositories should therefore not be confused with the entire SDK being purely open-source software.

FAIRINO

return

In FAIRINO collaborative robots, the Robot Arm and Control Box handle motion control, while the WebAPP / Teach Pendant provides the teaching and operation environment. Lua is used for robot programs running on the Controller. Separately, official SDKs allow an external PC to directly control joint / Cartesian motion, jogging, servo motion, I/O, status acquisition, and other functions.

Official SDKs for Python, C++, C#, and Java are published on GitHub, and the Python SDK is released under Apache-2.0. Consequently, when constructing a custom control class in Python, it is relatively straightforward to use the manufacturer’s official SDK directly as the foundation, without requiring a third-party wrapper.

Dobot

return

In Dobot’s CR / CRA collaborative robot series, the Robot Arm and Controller handle motion control, while DobotStudio Pro provides the environment for teaching, operation, and programming. For control from an external PC, the Controller’s TCP/IP protocol is published, with management commands, motion commands, and real-time feedback organized into separate communication channels.

The official GitHub repositories provide TCP-IP-4Axis-Python, which uses the TCP/IP protocol from Python, under the MIT License, as well as ROS / ROS2 resources. This makes it relatively easy to trace the implementation from the communication protocol through to the Python control class, and to build an independent device-control layer.

FANAC

return

Various aspects of FANAC control in SUSANOO

…

Loose Coupling at the Device-Server Level

return

SUSANOO (provisional name) is centered on a loosely coupled system architecture at the level of individual device servers, rather than building a large overarching framework for automation or autonomous operation. It goes without saying that this is one response to the era of physical AI.

The reason is that, regardless of what general-purpose APIs are prepared or what enormous framework is designed around a larger architecture, higher-level instruction and execution systems—including AI—are likely to continue changing substantially.

What will remain as the system backend is a minimal, device-level architecture that is easy to maintain. Intelligent functionality can be left to the layers above it.

Higher-level experimental sequences and approaches to intelligence will continue to evolve. In contrast, the components that remain useful over the long term are maintainable, device-level components. SUSANOO aims to keep this lower layer as simple as possible, allowing users to build higher-level intelligence and automation freely.

Automated and Autonomous Experiments Through Integration with Analysis

return

In SUSANOO (provisional name), users can work with individual devices without needing to be aware of the network, even when those devices are deployed in a distributed environment. In other words, from the user’s perspective, the hardware is simply a device object.

What does this mean?

It means that device objects can be treated and combined in the same way as program objects used for analysis.

By loosely coupling device objects that perform measurements with program objects that perform analysis, visualization, and decision-making, it becomes straightforward to develop autonomous automated experiments: measurement results are analyzed, and the analysis is used to determine the next operation or measurement conditions.

Large frameworks depend heavily on the technologies and requirements of their time and can become obsolete in a short period, even after they have been built. Moreover, the larger a framework becomes, the greater the cost of continuously maintaining, renewing, and migrating it.

To preserve and accumulate the assets needed for automated and autonomous experiments over time, while updating them as technologies evolve, it is important to build individual functions as small units that can be loosely coupled as distributed objects.

This kind of micro-level design and loose coupling of distributed objects is the purpose of this project.

●

What Is a Distributed System?

return

SUSANOO’s distributed environment was not constructed simply by selecting a particular communication method or framework. Several control systems actually operated at synchrotron radiation facilities differ in where they assign responsibility for distributed communication, device servers, management, and operations. Taking those architectures and operational practices into account, SUSANOO selects the functionality needed for experimental environments ranging from individual laboratories to roughly one beamline at SPring-8.

In SPring-8’s MADOCA/DARUMA, message servers and instrument control are separated, allowing distributed control—including message routing across nodes—to be handled as shared infrastructure. Because inter-node communication is itself a function of the control infrastructure, a single coherent system can support configurations spanning multiple networks and large numbers of devices.

TANGO, originating at ESRF, centers on Devices, Device Classes, and Device Servers and treats devices as distributed objects. It provides a consistent control-system mechanism that also encompasses management functions such as device-server startup, name resolution, and databases. SUSANOO’s terminology and concepts of Device, DeviceClass, and Device Server are also strongly influenced by TANGO.

By contrast, SPring-8’s BL774 is based on clients accessing individual device servers directly, rather than placing full-scale distributed routing in the common protocol. By relying primarily on REST APIs and Web technologies, this approach seeks to reduce operational costs, including deployment, debugging, and maintenance, as well as the effort required to develop the protocol itself.

These differences are not simply differences in the number of features or questions of which system is superior. If more distributed-control functionality is placed in the protocol or framework, message routing, asynchronous communication, event distribution, name resolution, startup management, and related functions can be used as shared infrastructure. The tradeoff is that the shared infrastructure itself must be continuously deployed, operated, and maintained.

Conversely, in an architecture that keeps individual device servers as independent as possible and connects to them directly using widely used communication technologies, the shared infrastructure offers fewer functions, but devices are easier to add or replace individually, and a small experimental environment is easier to keep small.

Ultimately, the choice is:

whether to make the protocol more sophisticated, the framework more sophisticated, or operations more sophisticated—or to limit the intended application and scale so that the shared infrastructure can remain small.

SUSANOO targets at most a single SPring-8 beamline and, more typically, a laboratory experimental environment. At this scale, rather than requiring MADOCA/DARUMA-style inter-node routing throughout the system, it adopts independent BL774-style device servers as its foundation and selects only the communication functions needed for each application.

In other words, the goal is not to build another full-stack distributed control system like MADOCA/DARUMA or TANGO.

Instead, the DeviceClass responsible for instrument-specific control is treated as a fundamental unit intended for long-term use, while communication, higher-level experimental sequences, analysis, automation, and related functions are combined around it as needed. By limiting the responsibilities of the shared infrastructure according to the target scale, individual instrument-control assets can be maintained independently of a particular framework or communication method.

The important point here is not to make the communication method the fundamental unit. SUSANOO’s fundamental unit is the DeviceClass, independent of any particular communication protocol or framework. A DeviceClass can be used on its own; a communication Frame is attached only when network access is required. REST / FastAPI, gRPC, TANGO, and potentially DDS in the future are treated as interchangeable communication layers outside the DeviceClass.

The distributed-control models and inter-node communication concepts underlying this decision are summarized below.

  1. Distributed models for instrument control
    Differences in architecture and operation among centralized systems, device-server systems, full-scale distributed control, BL774, TANGO, MADOCA, and related approaches.
  2. Fundamentals of distributed-node communication
    REQ/REP, ROUTER/DEALER, PUB/SUB, and the communication models of BL774, TANGO, MADOCA/DARUMA, ROS2, and related systems.

Distributed Systems in SUSANOO

return

Like BL774, SUSANOO’s basic model is a server–client architecture in which clients connect directly to the device servers they need.

In terms of its communication model, interactions with individual devices are essentially completed through request/reply exchanges. Even when multiple devices are used, a central message router is not required: the client connects separately to each device server it needs. The system does not assume that all device servers must be interconnected by a single distributed protocol.

Under this architecture, each device server is largely independent. Meanwhile, the client uses a transparent proxy, so users can interact with network-connected devices much like local Python objects. Thus, keeping the communication infrastructure small does not require exposing low-level communication operations to experimental programs.

The REST API used as the primary interface in BL774 is not designed for high-speed communication. Nevertheless, the widespread adoption, broad ecosystem, and simplicity of web-based technologies are difficult to dismiss. Libraries, development environments, and debugging tools are widely available, and even developers unfamiliar with a particular control framework can use them relatively easily.

For device-control operations such as moving motors, setting measurement conditions, and retrieving status, where communication time does not dominate overall device operation, development efficiency, readability, maintainability, and the use of widely established technologies matter more than REST API speed. SUSANOO, positioned as a subset of BL774, follows this basic approach.

On the other hand, some applications, such as image transfer, high-frequency data exchange, and event-driven processing, require faster communication or different communication models. In these areas, messaging technologies such as ZMQ / CORBA and PUB/SUB communication, as used in MADOCA/DARUMA and TANGO, can be advantageous.

While maintaining compatibility with the web technology ecosystem, SUSANOO allows gRPC to be selected for applications requiring high-speed binary transfer. gRPC supports binary transfer using Protocol Buffers, complementing REST for applications where REST is less suitable, such as image transfer. BL774 itself is also being extended to gRPC, so this is also one aspect of SUSANOO’s BL774 compatibility.

As illustrated by DENSO WAVE’s adoption of gRPC in ORiN3, using general-purpose RPC technologies for device-control interfaces is no longer unusual. Rather than fixing either REST or gRPC as the system-wide standard, SUSANOO selects a communication Frame according to the device and the communication speed required.

DDS is another technology for constructing a distributed environment itself. Adopting DDS as the system foundation from the outset is also a valid design choice, with ROS2 being a representative example. Since SUSANOO handles robots, connectivity with DDS / ROS2 is important as well.

However, although SUSANOO includes a BL774 compatibility layer for use at SPring-8, it does not make any particular communication mechanism—including BL774—a mandatory foundation for DeviceClass. It connects to DDS / ROS2 where DDS is appropriate, uses gRPC when high-speed RPC is needed, and uses REST / FastAPI for ordinary device control. When integration with a TANGO environment is required, the TANGO Frame is used.

In other words, unifying communication protocols is not itself a goal of SUSANOO.

DeviceClass
    ├─ ese774 Frame (REST / FastAPI), SPring-8 compatibility layer
    ├─ gRPC Frame, high-speed communication layer
    ├─ TANGO Frame, layer for using ESRF resources
    └─ DDS Frame, for advanced routing and use of ROS2 resources

By separating device-specific control from communication, DeviceClass remains a long-lived asset, while communication methods can be selected and replaced according to the application.

The aim is to minimize the need to rebuild device control itself when higher-level experimental sequences, analysis, automation, or AI architectures change. This is the fundamental approach to distributed environments in SUSANOO.

●

Summary of SUSANOO’s Design Philosophy

return

SUSANOO is based on a simple DeviceClass-oriented architecture.

Its fundamental unit is an individual device-control class that does not depend on a particular framework or communication protocol. In a sense, SUSANOO itself is not even a framework.

Each device-control class can be used independently. Only when network access is required is a thin communication layer—such as REST / FastAPI, gRPC, or TANGO—added for the particular application. These communication layers are interchangeable, and the device-control class itself does not depend on any specific communication method.

Through these thin communication layers, multiple DeviceClasses can be connected as device objects as needed. In principle, SUSANOO also does not attempt to standardize APIs at the framework level, except where there is a clear purpose for doing so, such as robot APIs.

●

Sample Experimental Scripts and Environment Setup Documentation

return (*) Documentation for students in the laboratory

Ease of use for end users controlling experiments is SUSANOO’s ultimate goal. SUSANOO users do not need to write or understand complicated programs for robot control or communication. They do, however, need some knowledge of Python.

For students, setting up the server PC and Python environment is probably a greater obstacle than installing COBOTTA or SUSANOO itself. The following records students’ trial and error.

Ohara Lab Slack Robo Channel

●

Computational and Analysis Objects

return

Computational and analysis objects are provided to work together with device servers (device classes) that control experiments.

Computation and Data Analysis (RMC): Source

return Primarily computation and data analysis using reverse Monte Carlo (RMC), along with supporting tools.

Computation and Data Analysis (MD): Source

return (*) As of 2026/03/03, access is restricted.

Primarily computation and data analysis using classical molecular dynamics (MD), along with supporting tools.

Computation and Data Analysis (MLP): Source

return

Primarily computation and data analysis using machine-learning potentials (MLP), along with supporting tools.

Computation and Data Analysis (DFT): Source

return

Primarily computation and data analysis using density functional theory (DFT) / first-principles MD, along with supporting tools.

●

Previous Articles

return

Previous articles on the fundamentals of computational methods and their applications.

return

Main Developers

  1. K.Ohara
  2. K.Kobayashi
  3. K.Watanabe
  4. R.Hinohara
  5. K.Nakada