# H??ng d?n s? d?ng RobotStateMachine

## Gi?i thi?u

`RobotStateMachine` là m?t singleton service qu?n lư tr?ng thái c?a mobile robot s? d?ng Hierarchical State Machine pattern v?i th? vi?n Appccelerate.StateMachine.

## C?u trúc Hierarchical State Machine

### Root States (C?p 1)
- **System**: Tr?ng thái h? th?ng
  - Initializing: ?ang kh?i t?o
  - Standby: Ch? s?n sàng
  - Shutting_Down: ?ang t?t

- **Auto**: Ch? ?? t? ??ng
  - Idle: R?nh r?i, s?n sàng nh?n l?nh
  - Executing: ?ang th?c hi?n nhi?m v?
    - Moving: ?ang di chuy?n
      - Navigation: ?i?u h??ng
      - Avoidance: Tránh ch??ng ng?i v?t
      - Approach: Ti?p c?n m?c tiêu
      - Tracking: Theo dơi m?c tiêu
      - Repositioning: ?i?u ch?nh v? trí
    - ACT: Th?c hi?n action
      - Docking: ?ang dock
      - Docked: ?ă dock
      - Charging: ?ang s?c
      - Undocking: ?ang undock
      - Loading: ?ang t?i hàng
      - Unloading: ?ang d? hàng
      - TechAction: Action k? thu?t
  - Paused: T?m d?ng
  - Canceling: ?ang h?y
  - Recovering: ?ang khôi ph?c
  - Remote_Override: ?i?u khi?n t? xa

- **Manual**: Ch? ?? th? công
- **Service**: Ch? ?? b?o tŕ
- **Stop**: Tr?ng thái d?ng
- **Fault**: Tr?ng thái l?i

## Cách s? d?ng

### 1. ??ng kư Service (trong Program.cs)

```csharp
// ??ng kư nh? Singleton
builder.Services.AddSingleton<RobotStateMachine>();
```

### 2. Kh?i t?o State Machine

```csharp
public class RobotController
{
    private readonly RobotStateMachine _stateMachine;
    
    public RobotController(RobotStateMachine stateMachine)
    {
        _stateMachine = stateMachine;
        
        // Kh?i t?o state machine
        _stateMachine.Initialize();
        
        // Ho?c s? d?ng async
        await _stateMachine.InitializeAsync();
    }
}
```

### 3. Subscribe vào State Change Events

```csharp
_stateMachine.StateChanged += (sender, e) =>
{
    Console.WriteLine($"State changed to: {e.NewState} via event: {e.EventType}");
};
```

### 4. Chuy?n ??i tr?ng thái

```csharp
// Hoàn thành kh?i t?o -> chuy?n sang Standby
await _stateMachine.FireAsync(RobotEventType.InitializeCompleted);

// Chuy?n sang ch? ?? Auto
await _stateMachine.FireAsync(RobotEventType.EnterAuto);

// B?t ??u th?c hi?n nhi?m v?
await _stateMachine.FireAsync(RobotEventType.StartExecution);

// Pause nhi?m v?
await _stateMachine.FireAsync(RobotEventType.PauseExecution);

// Resume nhi?m v?
await _stateMachine.FireAsync(RobotEventType.ResumeExecution);

// Hoàn thành nhi?m v?
await _stateMachine.FireAsync(RobotEventType.CompleteExecution);
```

### 5. Ki?m tra tr?ng thái hi?n t?i

```csharp
var currentState = _stateMachine.CurrentState;
var stateInfo = _stateMachine.GetStateInfo();
var isInitialized = _stateMachine.IsInitialized;
```

## Ví d? lu?ng ho?t ??ng

### Lu?ng kh?i ??ng robot

```csharp
// 1. Kh?i t?o state machine
await _stateMachine.InitializeAsync();
// State: System -> Initializing

// 2. Hoàn thành kh?i t?o
await _stateMachine.FireAsync(RobotEventType.InitializeCompleted);
// State: System -> Standby

// 3. Chuy?n sang ch? ?? Auto
await _stateMachine.FireAsync(RobotEventType.EnterAuto);
// State: Auto -> Idle
```

### Lu?ng th?c hi?n nhi?m v? di chuy?n

```csharp
// 1. B?t ??u th?c hi?n
await _stateMachine.FireAsync(RobotEventType.StartExecution);
// State: Auto -> Executing -> Moving -> Navigation

// 2. Phát hi?n ch??ng ng?i v?t
await _stateMachine.FireAsync(RobotEventType.StartAvoidance);
// State: Auto -> Executing -> Moving -> Avoidance

// 3. Ti?p t?c navigation
await _stateMachine.FireAsync(RobotEventType.StartNavigation);
// State: Auto -> Executing -> Moving -> Navigation

// 4. Hoàn thành di chuy?n
await _stateMachine.FireAsync(RobotEventType.CompleteMoving);
// State: Auto -> Idle
```

### Lu?ng th?c hi?n action (Docking & Charging)

```csharp
// 1. B?t ??u th?c hi?n
await _stateMachine.FireAsync(RobotEventType.StartExecution);
// State: Auto -> Executing -> Moving

// 2. Chuy?n sang ACT
await _stateMachine.FireAsync(RobotEventType.StartACT);
// State: Auto -> Executing -> ACT -> Docking

// 3. Hoàn thành docking
await _stateMachine.FireAsync(RobotEventType.CompleteDocking);
// State: Auto -> Executing -> ACT -> Docked

// 4. B?t ??u s?c
await _stateMachine.FireAsync(RobotEventType.StartCharging);
// State: Auto -> Executing -> ACT -> Charging

// 5. Hoàn thành s?c
await _stateMachine.FireAsync(RobotEventType.CompleteCharging);
// State: Auto -> Executing -> ACT -> Docked

// 6. Undocking
await _stateMachine.FireAsync(RobotEventType.StartUndocking);
// State: Auto -> Executing -> ACT -> Undocking

// 7. Hoàn thành undocking
await _stateMachine.FireAsync(RobotEventType.CompleteUndocking);
// State: Auto -> Executing -> ACT -> Docking

// 8. Hoàn thành ACT
await _stateMachine.FireAsync(RobotEventType.CompleteACT);
// State: Auto -> Idle
```

### X? lư Emergency Stop

```csharp
// Khi ?ang th?c hi?n nhi?m v?
await _stateMachine.FireAsync(RobotEventType.EnterStop);
// State: Stop

// Gi?i phóng stop
await _stateMachine.FireAsync(RobotEventType.ReleaseStop);
// State: Auto (quay l?i tr?ng thái tr??c ?ó nh? History)
```

## L?u ư quan tr?ng

1. **History Type**: 
   - System hierarchy s? d?ng `HistoryType.None` - không l?u tr?ng thái con
   - Auto hierarchy s? d?ng `HistoryType.Deep` - l?u toàn b? tr?ng thái con khi quay l?i

2. **Thread Safety**: State machine là thread-safe, có th? g?i t? nhi?u thread

3. **Exception Handling**: T?t c? các l?i khi fire event ??u ???c log và không throw exception

4. **Async Support**: Nên s? d?ng các ph??ng th?c Async ?? tránh blocking thread

5. **Singleton Pattern**: Service này nên ???c ??ng kư nh? Singleton ?? ??m b?o ch? có m?t instance duy nh?t

## Tích h?p v?i VDA5050

```csharp
public class VDA5050Handler
{
    private readonly RobotStateMachine _stateMachine;
    
    public void HandleOrder(Order order)
    {
        // Khi nh?n order m?i
        await _stateMachine.FireAsync(RobotEventType.StartExecution);
    }
    
    public void HandleInstantAction(InstantAction action)
    {
        switch (action.ActionType)
        {
            case "cancelOrder":
                await _stateMachine.FireAsync(RobotEventType.CancelExecution);
                break;
            case "pause":
                await _stateMachine.FireAsync(RobotEventType.PauseExecution);
                break;
        }
    }
    
    public string GetOperatingMode()
    {
        // Map state machine state to VDA5050 operatingMode
        return _stateMachine.CurrentState switch
        {
            RobotStateType.Auto => "AUTOMATIC",
            RobotStateType.Manual => "MANUAL",
            RobotStateType.Service => "SERVICE",
            _ => "SEMIAUTOMATIC"
        };
    }
}
```