Initial commit

2026-07-03 16:37:12 +07:00
commit 63b8c1ea8b
1931 changed files with 640587 additions and 0 deletions
--- a/srcs/RobotNet10/RobotApp/RobotNet10.RobotApp/Services/State/RobotStateMachineUsageExample.md
+++ b/srcs/RobotNet10/RobotApp/RobotNet10.RobotApp/Services/State/RobotStateMachineUsageExample.md
@@ -0,0 +1,248 @@
+# 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 trì
+- **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"
+        };
+    }
+}
+```