Feetech Servo SDK for C# (Windows)

A C# port of the Feetech SCServo SDK for controlling SC series servo motors on Windows. This library provides a complete C# implementation for Windows that maintains compatibility with the original protocol while leveraging C#'s type safety and modern language features.

Features

• Complete Protocol Implementation: Full support for SCServo communication protocol
• Windows Native: Built using System.IO.Ports.SerialPort for reliable Windows serial communication
• Type Safety: Leverages C#'s strong typing system for safer servo control
• Modern API: Clean, idiomatic C# interface with proper error handling
• Sync Operations: Support for synchronized read/write operations with multiple servos
• Easy to Use: Simple, intuitive API with comprehensive examples

Requirements

• .NET 8.0 or later
• Windows OS
• USB to TTL serial converter (compatible with 3.3V or 5V logic)
• SCServo with serial communication capability

Installation

Using .NET CLI

dotnet add package FeetechServoSDK

Manual Installation

1. Clone this repository
2. Build the project:

   dotnet build FeetechServoSDK/FeetechServoSDK.csproj

3. Add a project reference to your application

Quick Start

Basic Ping Example

using Feetech.ServoSDK;

// Initialize components
var portHandler = new PortHandler("COM3");  // Change to your COM port
var packetHandler = PacketHandlerFactory.CreatePacketHandler(0);

try
{
    // Open port and set baudrate
    portHandler.OpenPort();
    portHandler.SetBaudRate(1000000);
    
    // Ping servo
    var (modelNumber, result, error) = packetHandler.Ping(portHandler, 1);
    
    if (result == CommResult.Success && error.IsEmpty())
    {
        Console.WriteLine($"Servo found! Model number: {modelNumber}");
    }
    
    portHandler.ClosePort();
}
catch (Exception ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Reading and Writing Data

// Write goal position
var (writeResult, writeError) = packetHandler.Write2ByteTxRx(
    portHandler,
    servoId: 1,
    address: ControlTableAddress.GoalPosition,
    data: 2048
);

// Read present position
var (position, readResult, readError) = packetHandler.Read2ByteTxRx(
    portHandler,
    servoId: 1,
    address: ControlTableAddress.PresentPosition
);

Console.WriteLine($"Current position: {position}");

Synchronized Operations

// Create sync write group
var syncWrite = new GroupSyncWrite(
    portHandler,
    packetHandler,
    ControlTableAddress.GoalPosition,
    dataLength: 2
);

// Add multiple servos
syncWrite.AddParam2Byte(servoId: 1, data: 1000);
syncWrite.AddParam2Byte(servoId: 2, data: 2000);
syncWrite.AddParam2Byte(servoId: 3, data: 3000);

// Execute synchronized write
var result = syncWrite.TxPacket();

API Documentation

Core Components

PortHandler

Manages serial port communication with the servo controller.

public class PortHandler : IPortHandler, IDisposable
{
    public PortHandler(string portName);
    public void OpenPort();
    public void ClosePort();
    public void SetBaudRate(uint baudRate);
    public byte[] ReadPort(int length);
    public int WritePort(byte[] data);
    public static string[] GetAvailablePorts();
}

PacketHandler

Handles SCServo protocol packet communication.

public interface IPacketHandler
{
    (ushort modelNumber, CommResult result, ProtocolError error) Ping(IPortHandler port, byte servoId);
    (byte data, CommResult result, ProtocolError error) Read1ByteTxRx(IPortHandler port, byte servoId, byte address);
    (CommResult result, ProtocolError error) Write1ByteTxRx(IPortHandler port, byte servoId, byte address, byte data);
    // ... more methods for 2-byte and 4-byte operations
}

GroupSyncWrite

Performs synchronized write operations to multiple servos.

public class GroupSyncWrite
{
    public GroupSyncWrite(IPortHandler port, IPacketHandler packetHandler, byte startAddress, byte dataLength);
    public bool AddParam(byte servoId, byte[] data);
    public bool AddParam2Byte(byte servoId, ushort data);
    public CommResult TxPacket();
}

GroupSyncRead

Performs synchronized read operations from multiple servos.

public class GroupSyncRead
{
    public GroupSyncRead(IPortHandler port, IPacketHandler packetHandler, byte startAddress, byte dataLength);
    public bool AddParam(byte servoId);
    public CommResult TxRxPacket();
    public ushort GetData2Byte(byte servoId, byte address);
}

Constants and Enumerations

Communication Results

public enum CommResult : int
{
    Success = 0,
    PortBusy = -1,
    TxFail = -2,
    RxFail = -3,
    TxError = -4,
    RxTimeout = -6,
    RxCorrupt = -7,
    NotAvailable = -9
}

Control Table Addresses

public static class ControlTableAddress
{
    public const byte TorqueEnable = 40;
    public const byte GoalPosition = 42;
    public const byte GoalSpeed = 46;
    public const byte PresentPosition = 56;
}

Protocol Errors

[Flags]
public enum ProtocolError : byte
{
    None = 0,
    Voltage = 1,
    Angle = 2,
    Overheat = 4,
    Overload = 32
}

Examples

The library includes several example applications in the Examples folder:

1. Ping Example

• Basic servo detection and communication test
• Demonstrates connection setup and basic ping operation
• Run: dotnet run --project Examples/PingExample

2. Read/Write Example

• Individual servo position control
• Shows reading present position and setting goal position
• Includes motion monitoring and error handling
• Run: dotnet run --project Examples/ReadWriteExample

3. Sync Read/Write Example

• Multi-servo coordinated control
• Demonstrates synchronized operations
• Shows how to control multiple servos simultaneously
• Run: dotnet run --project Examples/SyncReadWriteExample

Configuration

Finding Your COM Port

// List available COM ports
var ports = PortHandler.GetAvailablePorts();
foreach (var port in ports)
{
    Console.WriteLine(port);
}

Protocol Configuration

Set the correct protocol endianness for your servo series:

// For STS/SMS series (most common)
var packetHandler = PacketHandlerFactory.CreatePacketHandler(0);

// For SCS series
var packetHandler = PacketHandlerFactory.CreatePacketHandler(1);

Baudrate Configuration

Common baudrates for SCServos:

portHandler.SetBaudRate(1000000);  // Most common
portHandler.SetBaudRate(115200);   // Alternative
portHandler.SetBaudRate(57600);    // Lower speed

Error Handling

The library uses C#'s native exception handling and tuple return types:

try
{
    portHandler.OpenPort();
    portHandler.SetBaudRate(1000000);
    
    var (data, result, error) = packetHandler.Read2ByteTxRx(portHandler, 1, 42);
    
    switch (result)
    {
        case CommResult.Success:
            if (error.IsEmpty())
                Console.WriteLine($"Data: {data}");
            else
                Console.WriteLine($"Protocol error: {error.GetDescription()}");
            break;
        case CommResult.RxTimeout:
            Console.WriteLine("Communication timeout - check connections");
            break;
        default:
            Console.WriteLine($"Communication error: {result.GetDescription()}");
            break;
    }
}
catch (SerialPortException ex)
{
    Console.WriteLine($"Port error: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"Unexpected error: {ex.Message}");
}

Thread Safety

The library is designed for single-threaded use. If you need to access servos from multiple threads:

1. Use a single dedicated thread for all servo communication
2. Implement your own synchronization mechanisms (e.g., lock statements)
3. Create separate PortHandler instances for each thread (not recommended)

Performance Considerations

• Batch Operations: Use sync read/write for multiple servos to reduce communication overhead
• Timeout Settings: Adjust packet timeouts based on your communication requirements
• Baudrate: Higher baudrates provide faster communication but may be less reliable over long distances

Troubleshooting

Common Issues

1. Access Denied to COM Port

   • Close other applications using the port
   • Check Windows Device Manager for port conflicts
   • Run your application with appropriate permissions

2. No Response from Servo

   • Check power supply
   • Verify baudrate settings
   • Ensure correct servo ID
   • Check cable connections

3. Communication Errors

   • Reduce baudrate
   • Check for electromagnetic interference
   • Verify protocol endianness setting
   • Ensure USB drivers are installed

Debug Mode

Enable detailed logging:

#if DEBUG
Console.WriteLine($"Communication result: {result.GetDescription()}");
Console.WriteLine($"Protocol error: {error.GetDescription()}");
#endif

Compatibility

Supported Servo Models

• STS Series: Smart Serial Servo (most common)
• SMS Series: Smart Serial Servo with magnetic encoder
• SCS Series: Smart Serial Servo with different protocol endianness

Platform Requirements

• Windows 10 or later
• .NET 8.0 or later

Hardware Requirements

• USB to TTL serial converter (compatible with 3.3V or 5V logic)
• SCServo with serial communication capability
• Appropriate power supply for your servo model

Building from Source

# Clone the repository
git clone https://github.com/yourusername/feetech-servo-sdk-csharp.git
cd feetech-servo-sdk-csharp

# Build the library
dotnet build FeetechServoSDK/FeetechServoSDK.csproj

# Build and run an example
dotnet run --project Examples/PingExample

License

This C# port maintains compatibility with the original Feetech library licensing terms.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all examples still work
5. Submit a pull request

Acknowledgments

This is a C# port of the Swift library by FyrbyAdditive, which itself is based on the original Feetech Python library. Special thanks to the original authors for their excellent work.

Support

For issues specific to this C# port, please open an issue on the repository. For general SCServo questions, refer to the original Feetech documentation.