hdc-rs 0.1.2

Rust client library for HarmonyOS Device Connector (HDC)
Documentation

HDC-RS

Crates.io Documentation License Rust Version

A pure Rust implementation of the HarmonyOS Device Connector (HDC) client library, providing both async and blocking APIs for interacting with HarmonyOS/OpenHarmony devices.

Note: HDC is to HarmonyOS what ADB is to Android - a bridge for device communication, debugging, and development.

✨ Features

  • 🚀 Async/await - Built on Tokio for efficient async I/O
  • 🔄 Blocking API - Synchronous wrapper for FFI bindings (PyO3, JNI, etc.)
  • 📱 Device Management - List, connect, and monitor devices
  • 💻 Shell Commands - Execute commands on devices with full output
  • 🔌 Port Forwarding - TCP, Unix sockets, JDWP, and Ark debugger support
  • 📦 App Management - Install/uninstall HAP and HSP packages
  • 📁 File Transfer - Efficient bidirectional file transfer with compression
  • 🔍 Device Monitoring - Real-time device connection/disconnection events
  • 📋 Log Streaming - Continuous or buffered hilog reading
  • 🛡️ Type-safe API - Rust's type system ensures correctness
  • ⚡ Zero-copy - Efficient data handling with bytes crate
  • 🎯 Error Handling - Comprehensive error types with context

📋 Table of Contents

🔧 Installation

Prerequisites

  • Rust 1.70 or later
  • HDC server must be installed and running
  • A HarmonyOS/OpenHarmony device connected via USB or network

Add to Your Project

Add this to your Cargo.toml:

[dependencies]

hdc-rs = "0.1"

tokio = { version = "1", features = ["full"] }

Feature Flags

  • blocking - Enable synchronous/blocking API for FFI bindings
[dependencies]

hdc-rs = { version = "0.1", features = ["blocking"] }

🚀 Quick Start

Async API (Recommended)

use hdc_rs::HdcClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to HDC server
    let mut client = HdcClient::connect("127.0.0.1:8710").await?;
    
    // List connected devices
    let devices = client.list_targets().await?;
    println!("Devices: {:?}", devices);
    
    if devices.is_empty() {
        println!("No devices connected!");
        return Ok(());
    }
    
    // Select and connect to first device
    client.connect_device(&devices[0]).await?;
    println!("Connected to device: {}", devices[0]);
    
    // Execute shell command on the selected device
    let output = client.shell("ls -l /data").await?;
    println!("Output:\n{}", output);
    
    Ok(())
}

Blocking API (for FFI/PyO3)

Enable the blocking feature for synchronous API:

[dependencies]

hdc-rs = { version = "0.1", features = ["blocking"] }


use hdc_rs::blocking::HdcClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to HDC server (synchronous!)
    let mut client = HdcClient::connect("127.0.0.1:8710")?;
    
    // List connected devices
    let devices = client.list_targets()?;
    println!("Devices: {:?}", devices);
    
    if !devices.is_empty() {
        // Connect and execute command
        client.connect_device(&devices[0])?;
        let output = client.shell("uname -a")?;
        println!("Output: {}", output);
    }
    
    Ok(())
}

📚 Examples

The repository includes several examples demonstrating different features:

Example Description Command
list_devices List all connected devices cargo run --example list_devices
simple_shell Interactive shell session cargo run --example simple_shell
blocking_demo Synchronous API demo cargo run --example blocking_demo --features blocking
device_monitor Monitor device connections cargo run --example device_monitor
file_demo File transfer operations cargo run --example file_demo
forward_demo Port forwarding setup cargo run --example forward_demo
app_demo App install/uninstall cargo run --example app_demo
hilog_demo Device log streaming cargo run --example hilog_demo
comprehensive All features combined cargo run --example comprehensive

Running Examples

# List all connected devices

cargo run --example list_devices


# Blocking API demo (synchronous)

cargo run --example blocking_demo --features blocking


# Monitor device connections/disconnections

cargo run --example device_monitor


# Interactive shell

cargo run --example simple_shell


# File transfer demo

cargo run --example file_demo


# Port forwarding demo

cargo run --example forward_demo


# App installation demo

cargo run --example app_demo


# Hilog (device logs) demo

cargo run --example hilog_demo


# Comprehensive example (all features)

cargo run --example comprehensive


# Enable debug logging for troubleshooting

RUST_LOG=hdc_rs=debug cargo run --example list_devices

📖 API Documentation

For detailed API documentation, visit docs.rs/hdc-rs.

Core Types

  • HdcClient - Main async client for HDC communication
  • blocking::HdcClient - Synchronous wrapper for FFI bindings
  • HdcError - Comprehensive error type with context
  • ForwardNode - Port forwarding endpoint specification
  • InstallOptions / UninstallOptions - App management options
  • FileTransferOptions - File transfer configuration

🏗️ Architecture

System Overview

┌─────────────────┐
│   Your App      │  ◄── Your Rust application
└────────┬────────┘
         │ (uses hdc-rs API)
         ▼
┌─────────────────┐
│    hdc-rs       │  ◄── This library (Rust)
│  ┌───────────┐  │
│  │  Client   │  │  - Connection management
│  │  Protocol │  │  - Packet codec
│  │  Commands │  │  - Error handling
│  └───────────┘  │
└────────┬────────┘
         │ (TCP socket: 127.0.0.1:8710)
         ▼
┌─────────────────┐
│  HDC Server     │  ◄── Native HDC daemon
│  (daemon)       │
└────────┬────────┘
         │ (USB/TCP connection)
         ▼
┌─────────────────┐
│ HarmonyOS       │  ◄── Target device
│ Device          │
└─────────────────┘

Project Structure

hdc-rs/
├── hdc-rs/              # Core Rust library
│   ├── src/
│   │   ├── lib.rs       # Public API
│   │   ├── client.rs    # HdcClient implementation
│   │   ├── blocking.rs  # Synchronous wrapper
│   │   ├── error.rs     # Error types
│   │   ├── app.rs       # App management
│   │   ├── file.rs      # File transfer
│   │   ├── forward.rs   # Port forwarding
│   │   └── protocol/    # Protocol implementation
│   │       ├── packet.rs    # Packet codec
│   │       ├── command.rs   # Command builders
│   │       └── channel.rs   # Channel management
│   └── Cargo.toml
├── hdc-py/              # Python bindings (PyO3)
│   ├── src/lib.rs
│   └── Cargo.toml
├── examples/            # Usage examples
└── tests/               # Integration tests

🔌 Protocol Details

Packet Format

HDC uses a simple length-prefixed binary protocol over TCP:

┌──────────────────────────────┐
│  4 bytes: Payload Length     │  (Big-endian u32)
├──────────────────────────────┤
│  N bytes: Payload Data       │  (Command + Arguments)
└──────────────────────────────┘

Connection Lifecycle

Client                           Server
  │                                │
  ├──── TCP Connect ──────────────>│
  │                                │
  │<──── Handshake (Channel ID) ───┤
  │                                │
  ├──── Connect Key ──────────────>│
  │                                │
  │<──── OK ────────────────────────┤
  │                                │
  ├──── Command ──────────────────>│
  │                                │
  │<──── Response ──────────────────┤
  │                                │
  ├──── Close ────────────────────>│
  │                                │

Supported Commands

Command Description Status
list targets List connected devices ✅ Implemented
checkserver Get server version ✅ Implemented
tmode port <port> Connect device over TCP ✅ Implemented
shell <cmd> Execute shell command ✅ Implemented
file send <local> <remote> Upload file ✅ Implemented
file recv <remote> <local> Download file ✅ Implemented
fport <local> <remote> Forward port ✅ Implemented
rport <remote> <local> Reverse forward ✅ Implemented
install <path> Install app ✅ Implemented
uninstall <pkg> Uninstall app ✅ Implemented
hilog Stream device logs ✅ Implemented
wait-for-device Wait for device ✅ Implemented

🐍 Python Bindings

This project includes Python bindings built with PyO3. See hdc-py/README.md for complete documentation.

Quick Example

from hdc_rs import HdcClient

# Connect and list devices
client = HdcClient("127.0.0.1:8710")
devices = client.list_targets()
print(f"Devices: {devices}")

if devices:
    # Execute command
    client.connect_device(devices[0])
    output = client.shell("uname -a")
    print(output)

Installation

cd hdc-py

pip install maturin

maturin develop  # Development mode

# or

maturin build --release  # Build wheel

pip install target/wheels/hdc_rs-*.whl

🔍 API Reference

HdcClient

Main client for HDC communication.

Connection Methods

  • connect(address) - Connect to HDC server
  • close() - Close connection
  • is_connected() - Check if connected

Device Management

  • list_targets() - List all connected devices
  • connect_device(device_id) - Select a device for subsequent commands
  • check_server() - Get server version
  • wait_for_device() - Block until a device is connected
  • monitor_devices(interval, callback) - Monitor device list changes with polling
    • interval: Polling interval (e.g., Duration::from_secs(2))
    • callback: Function called when device list changes, return false to stop

Command Execution

  • shell(cmd) - Execute shell command on the currently selected device
    • Important: Must call connect_device() first, or server will return error
  • shell_on_device(device_id, cmd) - Execute shell command on specific device
  • target_command(device_id, cmd) - Execute any command on specific device

Port Forwarding

  • fport(local, remote) - Forward local traffic to remote device
    • Example: fport(ForwardNode::Tcp(8080), ForwardNode::Tcp(8081))
  • rport(remote, local) - Reverse forward remote traffic to local host
    • Example: rport(ForwardNode::Tcp(9090), ForwardNode::Tcp(9091))
  • fport_list() - List all active forward/reverse tasks
  • fport_remove(task_str) - Remove a forward task by task string
    • Example: fport_remove("tcp:8080 tcp:8081")

Forward Node Types:

  • ForwardNode::Tcp(port) - TCP port
  • ForwardNode::LocalFilesystem(path) - Unix domain socket (filesystem)
  • ForwardNode::LocalReserved(name) - Unix domain socket (reserved)
  • ForwardNode::LocalAbstract(name) - Unix domain socket (abstract)
  • ForwardNode::Dev(name) - Device
  • ForwardNode::Jdwp(pid) - JDWP (Java Debug Wire Protocol, remote only)
  • ForwardNode::Ark { pid, tid, debugger } - Ark debugger (remote only)

App Management

  • install(paths, options) - Install application package(s)
    • paths: Single or multiple .hap/.hsp files or directories
    • options: InstallOptions::new().replace(true).shared(false)
      • replace: Replace existing application
      • shared: Install shared bundle for multi-apps
  • uninstall(package, options) - Uninstall application package
    • package: Package name (e.g., "com.example.app")
    • options: UninstallOptions::new().keep_data(true).shared(false)
      • keep_data: Keep the data and cache directories
      • shared: Remove shared bundle

Log Management

  • hilog(args) - Read device logs (buffered mode)
    • args: Optional hilog arguments (e.g., "-h" for help, "-t app" for app logs)
    • Returns all logs as a string after timeout
  • hilog_stream(args, callback) - Streaming hilog to given callback

File Transfer

  • file_send(local, remote, options) - Send file to device
    • local: Local file path
    • remote: Remote device path
    • options: FileTransferOptions - configure transfer behavior
  • file_recv(remote, local, options) - Receive file from device
    • remote: Remote device path
    • local: Local file path
    • options: FileTransferOptions - configure transfer behavior

File Transfer Options:

  • hold_timestamp(bool) - Preserve file timestamps (-a)
  • sync_mode(bool) - Only update if source is newer (-sync)
  • compress(bool) - Compress during transfer (-z)
  • mode_sync(bool) - Sync file permissions (-m)
  • debug_dir(bool) - Transfer to/from debug app directory (-b)am device logs continuously
    • args: Optional hilog arguments
    • callback: Function called for each log chunk, return false to stop streaming
    • Useful for real-time log monitoring

Usage Pattern

Option 1: Select device first (Recommended)

let mut client = HdcClient::connect("127.0.0.1:8710").await?;
let devices = client.list_targets().await?;

// Connect to device - this re-establishes connection with device ID in handshake
client.connect_device(&devices[0]).await?;

// Now shell commands will be routed to the selected device
let output = client.shell("ls /data").await?;

Option 2: Specify device per command

let mut client = HdcClient::connect("127.0.0.1:8710").await?;
let devices = client.list_targets().await?;

// Execute on specific device without selecting
let output = client.shell_on_device(&devices[0], "ls /data").await?;

Option 3: Port forwarding

use hdc_rs::{HdcClient, ForwardNode};

let mut client = HdcClient::connect("127.0.0.1:8710").await?;
let devices = client.list_targets().await?;
client.connect_device(&devices[0]).await?;

// Forward local TCP 8080 to device TCP 8081
client.fport(ForwardNode::Tcp(8080), ForwardNode::Tcp(8081)).await?;

// List all forwards
let tasks = client.fport_list().await?;
for task in tasks {
    println!("Forward: {}", task);
}

// Remove forward
client.fport_remove("tcp:8080 tcp:8081").await?;

Option 4: App management

use hdc_rs::{HdcClient, InstallOptions, UninstallOptions};

let mut client = HdcClient::connect("127.0.0.1:8710").await?;
let devices = client.list_targets().await?;
client.connect_device(&devices[0]).await?;

// Install app (replace if exists)
let opts = InstallOptions::new().replace(true);
client.install(&["app.hap"], opts).await?;

// Uninstall app (keep data)
let opts = UninstallOptions::new().keep_data(true);
client.uninstall("com.example.app", opts).await?;

Option 5: Device logs (hilog)

use hdc_rs::HdcClient;

let mut client = HdcClient::connect("127.0.0.1:8710").await?;
let devices = client.list_targets().await?;
client.connect_device(&devices[0]).await?;

// Get logs as buffered string
let logs = client.hilog(Some("-t app")).await?;
println!("App logs:\n{}", logs);

// Stream logs continuously
client.hilog_stream(None, |log_chunk| {
   

**Option 6: Monitor device connections**
```rust
use hdc_rs::HdcClient;
use std::time::Duration;

let mut client = HdcClient::connect("127.0.0.1:8710").await?;

// Wait for any device to connect (blocks until a device is available)
let device = client.wait_for_device().await?;
println!("Device connected: {}", device);

// Monitor device list changes in real-time
client.monitor_devices(Duration::from_secs(2), |devices| {
    println!("Device list updated: {} device(s)", devices.len());
    for device in devices {
        println!("  - {}", device);
    }
    true // Continue monitoring, return false to stop
}).await?;

Option 7: File transfer

use hdc_rs::{HdcClient, FileTransferOptions};

let mut client = HdcClient::connect("127.0.0.1:8710").await?;
let devices = client.list_targets().await?;
client.connect_device(&devices[0]).await?;

// Send file to device with options
let opts = FileTransferOptions::new()
    .hold_timestamp(true)   // Preserve timestamp
    .compress(true);         // Compress transfer
client.file_send("local.txt", "/data/local/tmp/remote.txt", opts).await?;

// Receive file from device
let opts = FileTransferOptions::new().sync_mode(true);
client.file_recv("/data/local/tmp/remote.txt", "local.txt", opts).await?;
``` print!("{}", log_chunk);
    true // Continue streaming, return false to stop
}).await?;

Error Handling

All methods return Result<T, HdcError>. The library provides comprehensive error types:

use hdc_rs::{HdcClient, HdcError};

match client.shell("ls").await {
    Ok(output) => println!("{}", output),
    Err(HdcError::NotConnected) => eprintln!("Not connected to HDC server!"),
    Err(HdcError::Timeout) => eprintln!("Command timeout!"),
    Err(HdcError::DeviceNotFound) => eprintln!("Device not found!"),
    Err(HdcError::ProtocolError(msg)) => eprintln!("Protocol error: {}", msg),
    Err(e) => eprintln!("Error: {}", e),
}

Available Error Types:

  • NotConnected - Not connected to HDC server
  • Timeout - Operation timeout
  • DeviceNotFound - Target device not found
  • ProtocolError - Protocol-level error
  • IoError - I/O error (network, file, etc.)
  • InvalidResponse - Invalid server response
  • CommandFailed - Command execution failed

💻 Development

┌─────────────────────┐
│ 4 bytes: length     │ (big-endian u32)
├─────────────────────┤
│ N bytes: data       │
└─────────────────────┘

Channel Handshake

  1. Client connects to server
  2. Server sends handshake with channel ID
  3. Client responds with connect key
  4. Connection established

Current Status

Implemented ✅

  • TCP connection management
  • Packet codec (length-prefixed protocol)
  • Channel handshake
  • Basic commands: list targets, shell, checkserver
  • Error handling
  • Async/await support

Planned 🚧

  • File transfer (file send, file recv)
  • Port forwarding (fport, rport)
  • App install/uninstall
  • USB connection support
  • Encryption (TLS-PSK)

Development

Prerequisites

  • Rust 1.70 or later
  • HDC server installed (from HarmonyOS SDK or OpenHarmony)
  • A HarmonyOS/OpenHarmony device or emulator

Building from Source

# Clone the repository

git clone https://github.com/oslo254804746/hdc-rs.git

cd hdc-rs


# Build the project

cargo build


# Build with release optimizations

cargo build --release


# Build with all features

cargo build --all-features

Running Tests

# Run all tests

cargo test


# Run integration tests (requires HDC server running)

cargo test --test integration_test


# Run specific test

cargo test test_name

Enable Debug Logging

Set the RUST_LOG environment variable for detailed logging:

# Linux/macOS

RUST_LOG=hdc_rs=debug cargo run --example list_devices


# Windows PowerShell

$env:RUST_LOG="hdc_rs=debug"; cargo run --example list_devices


# Windows CMD

set RUST_LOG=hdc_rs=debug && cargo run --example list_devices

Code Quality

# Format code

cargo fmt


# Lint with Clippy

cargo clippy -- -D warnings


# Check without building

cargo check

Documentation

# Generate and open documentation

cargo doc --open


# Generate documentation for all features

cargo doc --all-features --no-deps --open

🐛 Troubleshooting

Common Issues

"No devices found"

Solution:

  • Ensure HDC server is running: hdc start
  • Check device connection: hdc list targets
  • Verify device is authorized (check device screen for authorization prompt)
  • For network devices: hdc tconn <device_ip>:5555

Connection timeout

Symptoms: HdcError::Timeout or connection hangs

Solution:

  • Check if HDC server is listening on port 8710:
    • Windows: netstat -ano | findstr 8710
    • Linux/macOS: netstat -an | grep 8710 or lsof -i :8710
  • Restart HDC server: hdc kill then hdc start
  • Check firewall settings

Protocol errors

Symptoms: HdcError::ProtocolError or unexpected responses

Solution:

  • Ensure HDC server version compatibility (tested with 3.2.0+)
  • Check server version: hdc version or client.check_server().await?
  • Update HDC server to the latest version
  • Enable debug logging to inspect protocol messages

File transfer fails

Symptoms: HdcError::IoError during file operations

Solution:

  • Verify file paths are correct
  • Check device storage permissions
  • Ensure target directory exists on device
  • For large files, increase timeout or use compression

"Device not authorized"

Solution:

  • Check device for authorization dialog
  • Revoke and re-authorize: hdc kill-server then reconnect device
  • Check device developer options are enabled

Debug Tips

  1. Enable verbose logging:

    RUST_LOG=hdc_rs=trace cargo run --example your_example

  2. Use the comprehensive example:

    cargo run --example comprehensive

  3. Check HDC server logs:

    • Server logs are typically in the HDC installation directory
    • Use hdc -l 5 for verbose HDC logging

  4. Test with official HDC client:

    hdc list targets

hdc shell ls /data

    If the official client works but hdc-rs doesn't, please file an issue.

📊 Performance

  • Zero-copy parsing with bytes crate
  • Async I/O with Tokio for efficient concurrency
  • Connection pooling support (reuse connections)
  • Streaming support for large file transfers and log streaming

Benchmarks

Typical performance on a modern system:

  • Device listing: ~10-50ms
  • Shell command: ~20-100ms (depends on command)
  • File transfer: ~10-50 MB/s (depends on USB/network speed and device)

🗺️ Roadmap

Current Status (v0.1.0)

  • ✅ TCP connection management
  • ✅ Async/await API
  • ✅ Blocking API for FFI
  • ✅ Device management (list, connect, monitor)
  • ✅ Shell command execution
  • ✅ File transfer (send/recv)
  • ✅ Port forwarding (TCP, Unix sockets, JDWP, Ark)
  • ✅ App management (install/uninstall)
  • ✅ Log streaming (hilog)
  • ✅ Python bindings (PyO3)

🤝 Contributing

Contributions are welcome! Here's how you can help:

Ways to Contribute

  • 🐛 Report bugs - Open an issue with reproduction steps
  • 💡 Suggest features - Share your ideas for improvements
  • 📝 Improve documentation - Fix typos, add examples, clarify usage
  • 🔧 Submit pull requests - Fix bugs or implement new features
  • ⭐ Star the project - Show your support!

Development Workflow

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (cargo test)
  5. Run formatting (cargo fmt)
  6. Run linting (cargo clippy)
  7. Commit your changes (git commit -m 'Add amazing feature')
  8. Push to the branch (git push origin feature/amazing-feature)
  9. Open a Pull Request

Code Guidelines

  • Follow Rust naming conventions and idioms
  • Add tests for new functionality
  • Update documentation for API changes
  • Keep commits atomic and well-described
  • Ensure all CI checks pass

Testing

# Run all tests

cargo test


# Run specific test suite

cargo test --lib

cargo test --test integration_test


# Run with verbose output

cargo test -- --nocapture

📄 License

This project is dual-licensed under:

You may choose either license for your use.

🙏 Acknowledgments

  • HarmonyOS/OpenHarmony development tools team for HDC
  • Tokio project for excellent async runtime
  • PyO3 project for Rust-Python bindings
  • Rust community for amazing tools and libraries

📚 Resources

Official Documentation

Related Projects

Community

📈 Project Status

Build Status License Rust Version

Version: 0.1.0
Status: Active Development
Stability: Beta

Made with ❤️ by the HDC-RS contributors