import com.arcrobotics.ftclib.command.CommandScheduler

import com.arcrobotics.ftclib.command.CommandScheduler

CommandScheduler là lớp chịu trách nhiệm thực sự chạy các command.
Ở mỗi vòng lặp (iteration), scheduler sẽ:

• Thăm dò (poll) tất cả các nút (button) đã được đăng ký

• Lập lịch (schedule) các command để thực thi tương ứng

• Chạy phần thân (body) của tất cả các command đang được lập lịch

• Kết thúc (end) những command đã hoàn thành hoặc bị ngắt (interrupted)

CommandScheduler cũng gọi phương thức periodic() của mỗi Subsystem đã được đăng ký.

Using the Command Scheduler

(Sử dụng Command Scheduler)

CommandScheduler là một singleton, nghĩa là:

• Đây là một lớp có thể truy cập toàn cục

• Chỉ tồn tại một instance duy nhất

Do đó, để truy cập scheduler, người dùng phải gọi:

CommandScheduler.getInstance()

CommandScheduler.getInstance()

Trong hầu hết các trường hợp:

• Người dùng không cần gọi trực tiếp các phương thức của scheduler

• Gần như tất cả các phương thức quan trọng đều có wrapper tiện lợi ở nơi khác
  (ví dụ: trong các interface Command và Subsystem)

Tuy nhiên, có một ngoại lệ bắt buộc:
Người dùng phải gọi:

CommandScheduler.getInstance().run();

CommandScheduler.getInstance().run();

từ phương thức periodic() của opmode.

Nếu không làm điều này:

• Scheduler sẽ không bao giờ chạy

• Toàn bộ framework command-based sẽ không hoạt động

Scheduling a Command

(Lập lịch một Command)

Để lập lịch một command, người dùng gọi phương thức:

schedule()

Phương thức này:

• Nhận vào một command

• (Tùy chọn) chỉ định command đó có thể bị ngắt (interruptible) hay không

• Cố gắng thêm command vào danh sách các command đang chạy, tùy thuộc vào:

  • Command đó có đang chạy hay không

  • Các requirement của nó có đang khả dụng hay không

Nếu command được thêm thành công:

• Phương thức initialize() của command sẽ được gọi

The Scheduler Run Sequence

(Trình tự chạy của Scheduler)

Phương thức initialize() của mỗi Command được gọi khi command được schedule,
điều này không nhất thiết trùng với thời điểm scheduler chạy
(trừ khi command đó được gán trực tiếp với một nút bấm).

Vậy một vòng lặp duy nhất của phương thức run() trong scheduler thực sự làm gì?
Phần dưới đây mô tả chi tiết logic của một iteration.

Step 1: Run Subsystem Periodic Methods

(Bước 1: Chạy các phương thức periodic của Subsystem)

Trước tiên, scheduler gọi phương thức:

periodic()

của mỗi Subsystem đã được đăng ký.

Step 2: Poll Command Scheduling Triggers

(Bước 2: Thăm dò các trigger lập lịch command)

Tiếp theo, scheduler:

• Kiểm tra trạng thái của tất cả các trigger đã đăng ký

• Xem có command nào được gán với trigger đó cần được schedule hay không

Nếu điều kiện để schedule một command được thỏa mãn:

• Command đó sẽ được schedule

• Phương thức initialize() của command sẽ được gọi

Step 3: Run / Finish Scheduled Commands

(Bước 3: Chạy / Kết thúc các command đã được lập lịch)

Tiếp theo, scheduler:

1. Gọi phương thức execute() của tất cả các command đang được schedule

2. Sau đó gọi isFinished() để kiểm tra xem command đã hoàn thành hay chưa

Nếu command đã hoàn thành:

• Phương thức end() sẽ được gọi

• Command bị gỡ khỏi lịch chạy (de-scheduled)

• Các subsystem mà command yêu cầu sẽ được giải phóng

Lưu ý:

• Chuỗi gọi này được thực hiện theo thứ tự cho từng command

• Vì vậy:

  • Command này có thể gọi end()

  • Trước khi command khác kịp gọi execute()

• Các command được xử lý theo thứ tự chúng được schedule

Step 4: Schedule Default Commands

(Bước 4: Lập lịch Default Command)

Cuối cùng:

• Mỗi Subsystem đã đăng ký sẽ có default command của nó được schedule (nếu có)

Lưu ý:

• Phương thức initialize() của default command sẽ được gọi tại thời điểm này

Disabling the Scheduler

(Vô hiệu hóa Scheduler)

Scheduler có thể bị vô hiệu hóa bằng cách gọi:

CommandScheduler.getInstance().disable();

CommandScheduler.getInstance().disable();

Khi bị vô hiệu hóa:

• Các lệnh schedule() và run() của scheduler sẽ không làm gì cả

Scheduler có thể được bật lại bằng cách gọi:

CommandScheduler.getInstance().enable();

CommandScheduler.getInstance().enable();

Nếu bạn muốn reset scheduler (xóa instance hiện tại), gọi:

CommandScheduler.getInstance().reset();

CommandScheduler.getInstance().reset();

Command Event Methods

(Các phương thức sự kiện của Command)

Trong một số trường hợp, người dùng muốn scheduler:

• Thực thi một hành động tùy chỉnh

• Mỗi khi xảy ra một sự kiện của command
  (initialize, execute, hoặc end)

Điều này có thể thực hiện bằng các phương thức sau:

onCommandInitialize

Phương thức onCommandInitialize:

• Chạy một hành động được chỉ định

• Mỗi khi một command được khởi tạo (initialize)

onCommandExecute

Phương thức onCommandExecute:

• Chạy một hành động được chỉ định

• Mỗi khi một command được thực thi (execute)

onCommandFinish

Phương thức onCommandFinish:

• Chạy một hành động được chỉ định

• Khi một command kết thúc bình thường

• Tức là phương thức isFinished() trả về true

onCommandInterrupt

Phương thức onCommandInterrupt:

• Chạy một hành động được chỉ định

• Khi một command bị ngắt (interrupted)
  Ví dụ:

  • Bị hủy thủ công (explicitly canceled)

  • Bị thay thế bởi command khác dùng chung requirement