moto-hses usage guide

This skill provides guidance for using the moto-hses crate family to communicate with Yaskawa robot controllers via the High Speed Ethernet Server (HSES) protocol.

Note: The moto-hses crate family is a Rust client implementation for the HSES protocol. For the underlying protocol specification (message structure, command IDs, error codes), see the hses-protocol skill.

When to Use

• Implementing HSES communication with Yaskawa robot controllers in Rust
• Using moto_hses_client, moto_hses_proto, or moto_hses_mock crates
• Looking up API methods for robot control, status reading, variable access, file operations
• Writing tests with MockServer for HSES communication

Crate Overview

Crate	Purpose
moto_hses_client	HSES client for communicating with robot controllers
moto_hses_proto	Protocol types (Status, commands, etc.)
moto_hses_mock	Mock server for integration testing

Key Types

Type	Description
HsesClient	Basic HSES client (single-task usage)
SharedHsesClient	Thread-safe wrapper for concurrent access from multiple tasks
HsesClientOps	Trait for client abstraction (implemented by both client types)

Client Connection

Basic Usage

use moto_hses_client::{ClientConfig, HsesClient};
use moto_hses_proto::{ROBOT_CONTROL_PORT, FILE_CONTROL_PORT, TextEncoding};
use std::time::Duration;

// Create configuration
let config = ClientConfig {
    host: "192.168.1.100".to_string(),
    port: ROBOT_CONTROL_PORT,  // 10040 for robot control
    timeout: Duration::from_millis(3000),
    retry_count: 0,
    retry_delay: Duration::from_millis(200),
    buffer_size: 8192,
    text_encoding: TextEncoding::ShiftJis,
};

// Connect to controller
let client = HsesClient::new_with_config(config).await?;

Port Constants

Constant	Port	Usage
ROBOT_CONTROL_PORT	10040	Status, servo, job, variable, I/O, register operations
FILE_CONTROL_PORT	10041	File transfer operations (send/receive/delete)

Thread-Safe Client (SharedHsesClient)

For concurrent access from multiple tasks, wrap HsesClient with SharedHsesClient:

use moto_hses_client::{HsesClient, HsesClientOps, SharedHsesClient};

// Create HsesClient and wrap it for thread-safe access
let client = HsesClient::new_with_config(config).await?;
let shared_client = SharedHsesClient::new(client);

// Clone for each concurrent task
let client1 = shared_client.clone();
let client2 = shared_client.clone();

let handle1 = tokio::spawn(async move {
    client1.read_status().await
});

let handle2 = tokio::spawn(async move {
    client2.read_position(0).await
});

// Wait for all tasks
let (result1, result2) = tokio::try_join!(handle1, handle2)?;

HsesClientOps Trait

Both HsesClient and SharedHsesClient implement the HsesClientOps trait, enabling abstraction:

use moto_hses_client::HsesClientOps;

/// Accepts any client type implementing HsesClientOps
async fn check_status(client: &impl HsesClientOps) -> Result<bool, ClientError> {
    let status = client.read_status().await?;
    Ok(status.is_running())
}

// Works with both client types
check_status(&client).await?;        // HsesClient
check_status(&shared_client).await?; // SharedHsesClient

HsesClient API

Status & Control

Method	Description
read_status()	Read complete status (Data 1 & Data 2)
read_status_data1()	Read status data 1 only
read_status_data2()	Read status data 2 only
set_servo(bool)	Turn servo ON/OFF
set_hold(bool)	Set/release hold state
set_hlock(bool)	Set/release HLOCK (interlock PP and I/O)
set_cycle_mode(CycleMode)	Set cycle mode (Step/OneCycle/Continuous)

Status Convenience Methods

The Status struct returned by read_status() provides these helper methods:

Method	Description
is_running()	Check if robot is running
is_servo_on()	Check if servo is ON
has_alarm()	Check if alarm is active
has_error()	Check if error is active
is_teach_mode()	Check if in teach mode
is_play_mode()	Check if in play mode
is_remote_mode()	Check if in remote mode

CycleMode Enum (moto_hses_proto::CycleMode)

Variant	Description
CycleMode::Step	Execute one instruction at a time
CycleMode::OneCycle	Execute job once and stop
CycleMode::Continuous	Execute job repeatedly

Job Control

Method	Description
select_job(select_type, job_name, line_number)	Select job for execution
start_job()	Start the selected job
read_executing_job_info(task_type, attribute)	Read executing job info
read_executing_job_info_complete(task_type)	Read all job info attributes

JobSelectType Enum (moto_hses_proto::commands::JobSelectType)

Variant	Description
JobSelectType::InExecution	Select job for current task
JobSelectType::MasterJob	Select as master job

Note: Job name does not require .JBI extension.

Position

Method	Description
read_position(control_group)	Read current position

Alarm

Method	Description
read_alarm_data(instance, attribute)	Read alarm data
read_alarm_history(instance, attribute)	Read alarm history
reset_alarm()	Reset active alarms
cancel_error()	Cancel current error

AlarmAttribute Enum (moto_hses_proto::AlarmAttribute)

Variant	Description
AlarmAttribute::All	Read all alarm attributes
AlarmAttribute::Code	Read alarm code only
AlarmAttribute::Data	Read alarm data only
AlarmAttribute::Type	Read alarm type only
AlarmAttribute::Time	Read alarm time only
AlarmAttribute::Name	Read alarm name only

Alarm Instance Ranges

Range	Type
1-10	Major failure alarm history
1001-1010	Monitor alarm history

Variable (Single)

Method	Description
read_u8(index) / write_u8(index, value)	B-type (8-bit unsigned)
read_i16(index) / write_i16(index, value)	I-type (16-bit signed)
read_i32(index) / write_i32(index, value)	D-type (32-bit signed)
read_f32(index) / write_f32(index, value)	R-type (32-bit float)
read_string(index) / write_string(index, value)	S-type (string, 16 bytes max)

Variable (Multiple)

Method	Description
read_multiple_u8(start, count) / write_multiple_u8(start, values)	B-type
read_multiple_i16(start, count) / write_multiple_i16(start, values)	I-type
read_multiple_i32(start, count) / write_multiple_i32(start, values)	D-type
read_multiple_f32(start, count) / write_multiple_f32(start, values)	R-type
read_multiple_strings(start, count) / write_multiple_strings(start, values)	S-type

I/O

Method	Description
read_io(io_number) / write_io(io_number, value)	Single I/O
read_multiple_io(start, count) / write_multiple_io(start, data)	Multiple I/O

Register

Method	Description
read_register(number) / write_register(number, value)	Single register
read_multiple_registers(start, count) / write_multiple_registers(start, values)	Multiple registers

File

Note: File operations require connecting to FILE_CONTROL_PORT (10041), not ROBOT_CONTROL_PORT.

Method	Description
read_file_list(pattern)	Get file list (e.g., "*.JBI")
send_file(filename, content)	Send file to controller
receive_file(filename)	Receive file from controller
delete_file(filename)	Delete file from controller

Error Handling

All async methods return Result<T, ClientError>. Common error patterns:

use moto_hses_client::ClientError;

match client.read_status().await {
    Ok(status) => { /* handle success */ }
    Err(ClientError::TimeoutError(_)) => { /* connection timeout */ }
    Err(ClientError::ConnectionError(_)) => { /* I/O error */ }
    Err(ClientError::ConnectionFailed(retries)) => { /* connection failed after retries */ }
    Err(ClientError::ProtocolError(_)) => { /* protocol-level error */ }
    Err(ClientError::InvalidVariable(_)) => { /* invalid variable access */ }
    Err(ClientError::SystemError(_)) => { /* system error */ }
}

Testing

Unit Tests

Use the HsesClientOps trait (see HsesClientOps Trait section) for dependency injection and mock implementations in unit tests.

use moto_hses_client::{ClientError, HsesClientOps};
use moto_hses_proto::Status;

// Create a mock implementation for unit testing
struct MockClient {
    status: Status,
}

#[async_trait::async_trait]
impl HsesClientOps for MockClient {
    async fn read_status(&self) -> Result<Status, ClientError> {
        Ok(self.status.clone())
    }
    // ... implement other methods as needed
}

// Use in tests
async fn handler(client: &impl HsesClientOps) -> Result<bool, ClientError> {
    let status = client.read_status().await?;
    Ok(status.is_running())
}

Integration Tests with MockServer

Use moto_hses_mock::MockServer for integration testing with actual network communication.

use moto_hses_mock::{MockConfig, MockServer};

let config = MockConfig::new("127.0.0.1", 10040, 10041);
let server = Arc::new(MockServer::new(config).await?);

tokio::spawn({
    let server = Arc::clone(&server);
    async move { server.run().await.ok(); }
});
tokio::time::sleep(Duration::from_millis(200)).await;

State Access

// Get state reference
let state = server.state();

// Read state (async)
let guard = state.read().await;
assert!(guard.servo_on);
assert!(guard.get_running());

// Write state (async)
let mut guard = state.write().await;
guard.set_servo(true);
guard.set_hold(false);
guard.set_running(true);

MockState Methods

Method	Description
set_servo(bool)	Set servo ON/OFF state
set_hold(bool)	Set hold state
set_running(bool)	Set running state
get_running()	Get running state
set_executing_job(Option<ExecutingJobInfo>)	Set executing job info
get_variable(index)	Get variable value
set_variable(index, value)	Set variable value
get_io_state(io_number)	Get I/O state
set_io_state(io_number, state)	Set I/O state

If a method for the desired state doesn't exist, you can directly access the public fields of MockState (e.g., guard.status.data1.running).

Important Considerations

Port Conflict Avoidance

• Single-threaded Execution: Configure with RUST_TEST_THREADS = "1"
• Port Management: MockServer uses fixed ports (10040, 10041)
• Test Isolation: Independent MockServer instances prevent state interference between tests

Test Design Best Practices

1. State Management: Utilize MockServer's state modification interfaces
2. Wait for Async: Add small delays after server start and before assertions

Reference Examples (in references/examples/)

The references/examples/ directory contains sample code for various operations:

Example	Description
read_status.rs	Status reading and convenience methods
hold_servo_control.rs	Servo/Hold/Hlock control operations
cycle_mode_control.rs	Cycle mode setting
job_select.rs	Job selection
job_start.rs	Job execution
position_operations.rs	Robot position reading
alarm_operations.rs	Alarm data reading and reset
byte_variable_operations.rs	B-type variable (8-bit unsigned)
integer_variable_operations.rs	I-type variable (16-bit signed)
double_variable_operations.rs	D-type variable (32-bit signed)
real_variable_operations.rs	R-type variable (32-bit float)
string_variable_operations.rs	S-type variable (string)
io_operations.rs	I/O data reading and writing
register_operations.rs	Register data reading and writing
file_operations.rs	File transfer operations
read_executing_job_info.rs	Executing job information
mock_basic_usage.rs	MockServer setup and state configuration
shared_client.rs	Thread-safe SharedHsesClient for concurrent access

Note: For detailed API specifications, refer to the crate documentation on crates.io. The examples above focus on practical usage patterns.

Protocol Reference

For a complete mapping of HSES protocol commands to API methods, see Protocol Command Reference.