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

Key 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

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

Status Convenience Methods

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

CycleMode Enum (moto_hses_proto::CycleMode)

Job Control

JobSelectType Enum (moto_hses_proto::commands::JobSelectType)

Note: Job name does not require .JBI extension.

Position

Alarm

AlarmAttribute Enum (moto_hses_proto::AlarmAttribute)

Alarm Instance Ranges

Variable (Single)

Variable (Multiple)

I/O

Register

File

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

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

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:

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.