AgentSkillsCN

moto-hses-usage

moto-hses Rust crate使用指南。适用情况:实现与Yaskawa机器人控制器的HSES(高速以太网服务器)通信。

SKILL.md
--- frontmatter
name: moto-hses-usage
description: "moto-hses Rust crate usage guide. USE WHEN: implementing HSES (High Speed Ethernet Server) communication with Yaskawa robot controllers."

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

CratePurpose
moto_hses_clientHSES client for communicating with robot controllers
moto_hses_protoProtocol types (Status, commands, etc.)
moto_hses_mockMock server for integration testing

Key Types

TypeDescription
HsesClientBasic HSES client (single-task usage)
SharedHsesClientThread-safe wrapper for concurrent access from multiple tasks
HsesClientOpsTrait for client abstraction (implemented by both client types)

Client Connection

Basic Usage

rust
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

ConstantPortUsage
ROBOT_CONTROL_PORT10040Status, servo, job, variable, I/O, register operations
FILE_CONTROL_PORT10041File transfer operations (send/receive/delete)

Thread-Safe Client (SharedHsesClient)

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

rust
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:

rust
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

MethodDescription
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:

MethodDescription
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)

VariantDescription
CycleMode::StepExecute one instruction at a time
CycleMode::OneCycleExecute job once and stop
CycleMode::ContinuousExecute job repeatedly

Job Control

MethodDescription
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)

VariantDescription
JobSelectType::InExecutionSelect job for current task
JobSelectType::MasterJobSelect as master job

Note: Job name does not require .JBI extension.

Position

MethodDescription
read_position(control_group)Read current position

Alarm

MethodDescription
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)

VariantDescription
AlarmAttribute::AllRead all alarm attributes
AlarmAttribute::CodeRead alarm code only
AlarmAttribute::DataRead alarm data only
AlarmAttribute::TypeRead alarm type only
AlarmAttribute::TimeRead alarm time only
AlarmAttribute::NameRead alarm name only

Alarm Instance Ranges

RangeType
1-10Major failure alarm history
1001-1010Monitor alarm history

Variable (Single)

MethodDescription
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)

MethodDescription
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

MethodDescription
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

MethodDescription
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.

MethodDescription
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:

rust
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.

rust
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.

rust
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

rust
// 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

MethodDescription
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:

ExampleDescription
read_status.rsStatus reading and convenience methods
hold_servo_control.rsServo/Hold/Hlock control operations
cycle_mode_control.rsCycle mode setting
job_select.rsJob selection
job_start.rsJob execution
position_operations.rsRobot position reading
alarm_operations.rsAlarm data reading and reset
byte_variable_operations.rsB-type variable (8-bit unsigned)
integer_variable_operations.rsI-type variable (16-bit signed)
double_variable_operations.rsD-type variable (32-bit signed)
real_variable_operations.rsR-type variable (32-bit float)
string_variable_operations.rsS-type variable (string)
io_operations.rsI/O data reading and writing
register_operations.rsRegister data reading and writing
file_operations.rsFile transfer operations
read_executing_job_info.rsExecuting job information
mock_basic_usage.rsMockServer setup and state configuration
shared_client.rsThread-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.