# ================================
# Tactile Sensor Interface
# ================================

# Tactile sensor data
# Normal force, tangential force, tangential force direction, proximity value, state
class TouchFingerItem:
    normal_force1: int  # Normal force in 0.01 N. For example, 1000 means 1000 × 0.01 = 10 N. Range: 0 ~ 25 N
    tangential_force1: int  # Tangential force in 0.01 N. For example, 1000 means 1000 × 0.01 = 10 N. Range: 0 ~ 25 N
    tangential_direction1: int  # Tangential force direction, 0–359°. 0° is toward the fingertip; clockwise up to 359°. 65535 (0xFFFF) means invalid.
    self_proximity1: int  # Self-capacitance 1

class TouchFingerData:
    items: list[TouchFingerItem]

# Raw tactile data
class TouchRawData:
    thumb: list[int]
    index: list[int]
    middle: list[int]
    ring: list[int]
    pinky: list[int]
    description: str
    def desc(self) -> str: ...

"""
This document demonstrates dedicated tactile sensor interfaces for Revo1 Touch and Revo2 Touch robotic hands.

Tactile sensor features:
- Multi-dimensional force sensing: normal force, tangential force, tangential direction
- Proximity detection: self-capacitance and mutual capacitance
- Contact state recognition: no contact, static contact, sliding contact
- Real-time data stream: supports high-frequency acquisition and callbacks

Before use, make sure your device supports tactile sensors:
    device_info = device.get_device_info(slave_id=1)
    if device_info.is_touch():
        print("Device supports tactile sensors")
        if device_info.is_revo1_touch():
            print("Revo1 Touch - 1st Gen Tactile Version")
        elif device_info.is_revo2_touch():
            print("Revo2 Touch - 2nd Gen Tactile Version")

Usage flow:
1. Check if the device supports tactile sensors
2. Enable and initialize the tactile sensor system
3. Retrieve tactile data
4. Process tactile data and implement control logic
5. Calibrate zero drift and reset tactile sensors
"""

from typing import List, Optional, Callable, Any

# ================================
# Basic Tactile Sensor Interface
# ================================

def get_touch_sensor_enabled(self, slave_id: int) -> bool:
    """
    Check if the tactile sensor is enabled

    Args:
        slave_id: Device slave ID

    Returns:
        bool: True if enabled, False if disabled

    Notes:
        - Tactile sensors are disabled by default to save power
        - You must enable them to retrieve data
        - Applicable to all tactile-supported devices

    Example:
        if device.get_device_info(slave_id=1).is_touch():
            enabled = device.get_touch_sensor_enabled(slave_id=1)
            if not enabled:
                print("Tactile sensor is not enabled. Please enable it first.")
            else:
                print("Tactile sensor is enabled")
    """
    pass

def get_touch_sensor_fw_versions(self, slave_id: int) -> List[str]:
    """
    Get the firmware versions of tactile sensors

    Args:
        slave_id: Device slave ID

    Returns:
        List[str]: List of firmware versions for each finger

    Notes:
        - The tactile sensor must be enabled first
        - Each finger sensor may have a different firmware version
        - Version info is useful for diagnostics and compatibility checks

    Example:
        if device.get_touch_sensor_enabled(slave_id=1):
            versions = device.get_touch_sensor_fw_versions(slave_id=1)
            finger_names = ["Thumb", "Index", "Middle", "Ring", "Pinky"]

            for i, version in enumerate(versions):
                if i < len(finger_names):
                    print(f"{finger_names[i]} tactile sensor firmware version: {version}")
        else:
            print("Please enable the tactile sensor first")
    """
    pass

def touch_sensor_setup(self, slave_id: int, bits: int):
    """
    Enable and initialize the tactile sensor system

    Args:
        slave_id: Device slave ID
        bits: Bitmask specifying which sensors to enable
              - Use bitwise operations to select fingers
              - e.g., 0x1F (0b11111) enables all five fingers
              - e.g., 0x03 (0b00011) enables only thumb and index

    Bitmask:
        - Bit 0: Thumb
        - Bit 1: Index
        - Bit 2: Middle
        - Bit 3: Ring
        - Bit 4: Pinky

    Notes:
        - This is the first step before using tactile sensors
        - Sensors perform initialization and self-check when enabled
        - Initialization may take a few seconds

    Example:
        # Enable all tactile sensors
        device.touch_sensor_setup(slave_id=1, bits=0x1F)
        print("All tactile sensors enabled")

        # Enable thumb and index only
        device.touch_sensor_setup(slave_id=1, bits=0x03)
        print("Thumb and index tactile sensors enabled")

        # Enable index only
        device.touch_sensor_setup(slave_id=1, bits=0x02)
        print("Index tactile sensor enabled")
    """
    pass

def touch_sensor_reset(self, slave_id: int, bits: int):
    """
    Reset specified tactile sensors

    Args:
        slave_id: Device slave ID
        bits: Bitmask specifying which sensors to reset

    Notes:
        - Sensors return abnormal states during reset
        - Normal operation resumes after reset
        - Useful for resolving sensor errors or reinitialization
        - Reset does not affect the enabled state

    Example:
        # Reset all tactile sensors
        device.touch_sensor_reset(slave_id=1, bits=0x1F)
        print("All tactile sensors reset")

        # Reset thumb sensor only
        device.touch_sensor_reset(slave_id=1, bits=0x01)
        print("Thumb tactile sensor reset")
    """
    pass

def touch_sensor_calibrate(self, slave_id: int, bits: int):
    """
    Perform zero-drift calibration for tactile sensors

    Args:
        slave_id: Device slave ID
        bits: Bitmask specifying which sensors to calibrate

    Calibration notes:
        - Make sure the fingers are not touching anything
        - This removes zero-drift error
        - Recommended after temperature stabilization
        - Improves accuracy significantly

    When to calibrate:
        - First-time use
        - Large ambient temperature changes
        - Sensor readings show clear offset
        - Periodic maintenance

    Example:
        # Calibrate all tactile sensors
        print("Calibrating tactile sensors. Ensure fingers are not touching anything...")
        device.touch_sensor_calibrate(slave_id=1, bits=0x1F)
        print("Calibration completed")

        # Calibrate thumb only
        device.touch_sensor_calibrate(slave_id=1, bits=0x01)
        print("Thumb tactile sensor calibrated")
    """
    pass

def get_touch_raw_data(self, slave_id: int) -> TouchRawData:
    """
    Get raw tactile data (mainly for Revo1 Touch)

    Args:
        slave_id: Device slave ID

    Returns:
        TouchRawData: Object containing:
            - thumb: List[int] - raw thumb data
            - index: List[int] - raw index data
            - middle: List[int] - raw middle data
            - ring: List[int] - raw ring data
            - pinky: List[int] - raw pinky data
            - description: str - data description

        TouchRawData provides:
            - desc() -> str: Get description

    Notes:
        - Only for tactile-supported devices, mainly Revo1 Touch
        - Must enable tactile sensors first
        - Raw data requires manual parsing
        - Format may differ by sensor version

    Example:
        if device.get_device_info(slave_id=1).is_revo1_touch():
            if device.get_touch_sensor_enabled(slave_id=1):
                raw_data = device.get_touch_raw_data(slave_id=1)

                print(f"Thumb raw: {raw_data.thumb}")
                print(f"Index raw: {raw_data.index}")
                print(f"Description: {raw_data.desc()}")

                if len(raw_data.thumb) > 0:
                    avg_thumb = sum(raw_data.thumb) / len(raw_data.thumb)
                    print(f"Thumb average: {avg_thumb}")
    """
    pass


def get_single_touch_sensor_status(self, slave_id: int, index: int) -> TouchFingerItem:
    """
    Get tactile sensor data for a single finger

    Args:
        slave_id: Device slave ID
        index: Finger index (0–4, Thumb to Pinky)

    Notes:
        - The corresponding sensor must be enabled first

    Example:
        if device.get_device_info(slave_id=1).is_revo2_touch():
            thumb_status = device.get_single_touch_sensor_status(slave_id=1, index=0)
    """
    pass

def get_touch_sensor_status(self, slave_id: int) -> TouchFingerData:
    """
    Get tactile sensor data for all fingers

    Args:
        slave_id: Device slave ID

    Returns:
        TouchFingerData

    Notes:
        - More efficient than querying each finger individually
        - Suitable for multi-finger tactile processing

    Example:
        if device.get_device_info(slave_id=1).is_revo2_touch():
            touch_data = device.get_touch_sensor_status(slave_id=1)
            finger_names = ["Thumb", "Index", "Middle", "Ring", "Pinky"]
    """
    pass