API Document

#define

limit

#define limit(x,y) ;limitStart(x);y;limitEnd();

limitStart, limitEnd的綜合使用, 開啟執行時間限制, 執行指令y, 然後關閉限制例如:

limit(3600,
  forward(120) await;
  turnLeft(90) await;
);

此代碼表示向前直行和轉左90度需要在3600毫秒內完成, 否則將會停止並直接跳到外面

lamdba

#define lamdba []()

匿名函數的語法糖

await

#define await ;_lockthread();

為下一個指令提出鎖起線程的要求
例如:

lift(40);
forward(120) await;
turnLeft(90);

此代碼表示升降台升起和向前直行一起進行 , 等待向前直行指令完成後進行轉左90度, 無論升降台升起是否已經完成

redonly

#define redonly ;_redonly();

聲明下一個指令只適用於紅方區域的自動程序, 如果執行區域為藍區, 指令將不會被執行
例如:

redonly turnLeft(90) blueonly turnRight(90);

此代碼表示轉左90度只適用於紅色區域, 如果執行區域為藍區, 則會跳到轉右90度

blueonly

#define blueonly ;_blueonly();

聲明下一個指令只適用於藍方區域的自動程序, 如果執行區域為紅區, 指令將不會被執行
例如:

redonly turnLeft(90) blueonly turnRight(90);

此代碼表示轉左90度只適用於紅色區域, 如果執行區域為藍區, 則會跳到轉右90度

waiting

#define waiting(x) ;waitUntil([]()->bool{return x;});

waitUntil的語法糖, 暫停線程並等待直至條件成立
例如:

lift(40);
forward(120);
waiting(LiftTarget == 0 && MoveTargetL == 0);
...

此代碼表示升降台升起和向前直行一起進行, 等待兩個指令都完成後才繼續以下部分的指令

Arm

配置

馬達與感應器

type	name	detail
Motor	mtrArm	手臂

arm

action arm(const short speed, const int waitms = 0);

指定手臂馬達速度

參數:
- speed
  
  手臂的馬達速度, 範圍 -127 ~ +127
- waitms
  
  持續毫秒, 可選, 預設為 0
  
  不填寫 : 持續
  
  填寫 : 持續ms毫秒, 然後停止
返回: action結構以控制指令

Config

loadConfig

bool loadConfig();

載入設定檔, 此動作會覆蓋部分受設定檔影響的參數

返回: True 如果成功載入設定檔, 或者 False 如果不能打開或格式錯誤

saveConfig

bool saveConfig();

儲存設定檔, 此動作會將上次選擇的自動程序, 顏色區域以及除錯模式閥門記錄到設定檔中

返回: True 如果成功儲存設定檔, 或者 False 如果不能打開

Core

action_brake_mode_e

此枚舉定義了不同類型的制動模式
可使用於移動指令

Enum
BRAKE	0
HOLD	1
RELEASE	2

action_component_type_e

此枚舉定義了不同類型的制動模式

讓機械人移動的部件，例如四輪或全向輪底架
以角度為單位的部件，例如升降台
開關狀態的部件，例如轉盤或夾
以力量為單位的部件，例如無限循環的滾輪或忽略角度的手臂
能維持轉動速度的部件，例如轉輪發射器
步驟性的部件，例如位能發射器

Enum	Value
COMPONENT_MOVE	0
COMPONENT_FIXED_RANGE	1
COMPONENT_POLARITY	2
COMPONENT_POWER_DRIVE	3
COMPONENT_SPINNER	4
COMPONENT_SHOOTER	5

handler

此結構包含一個動作生命週期所使用的參數, 包括數據更新,狀態檢查,結束停止的處理函式及開始數值和時間及使用者後續設定的自定義事件等等. 使用 startHandler 函式激活, 系統會透過文字組成的金匙儲存在 _handler_map 字典中

fnc_update_

std::function<int(handler)> fnc_update_;

生命週期中數據更新的處理函式, 用於取得動作進度以啟動 to 事件

fnc_loop_

std::function<bool(handler,int)> fnc_loop_;

生命週期中狀態檢查的處理函式, 用於檢查動作是否完成以及更新馬達速度

fnc_stop_

std::function<void(handler)> fnc_stop_;

生命週期中結束停止的處理函式, 用於停止動作並且進行制動

compare_operator_

short compare_operator_;

原始感應器數據在動作進行時呈現上升 1 還是下降 -1
1 : target > now, -1 : target < now

start_value_

int start_value_;

原始感應器數據在動作開始前的數值

start_time_

uint32_t start_time_;

在動作開始前的時間值

waituntil_value_

int waituntil_value_ =- 1;

使用者設定, 同步等待到此進度,
-1 : 沒有設定, >= 0 : 目前進度高於此值時將會跳出同步等待

waituntil_time_

uint32_t waituntil_time_  = -1;

在動作開始前的時間值 -1 : 沒有設定, >= 0 : 目前時間值高於此值時將會跳出同步等待

thread_run_

bool thread_run_ = true;

生命週期是否繼續運行

fnc_event_to_

std::map<int,std::function<void()>> fnc_event_to_;

儲存自定義 to 事件
int : 進度(使用者單位), std::function : 事件函式

fnc_event_finish_

std::function<void()> fnc_event_finish_ = []{};

儲存自定義完結事件, std::function : 事件函式

action

此結構包含三個函式用於操作動作處理器, 作為動作處理器的介面, 可以讓使用者使用預設的函式進行操作, 包括設定同步等待限制以及自定義事件等等

id_

std::string id_ = "*";

動作處理器的唯一金匙

enable_wait_until_

bool enable_wait_until_ = true;

是否啟用同步等待的限制條件

awaitUntil

action& awaitUntil(const int value = -1, const int time = -1);

設定同步等待的限制條件, 只需要進度值和時間其中一方完成, 便會跳過同步等待, 兩種限制必須填寫其中一種

to

action& to(const int value, const std::function<void()> event);

設定觸發事件, 當進度值超過 value 數值時將會呼叫 event 函式, 事件處理函式會在動作的處理線程中進行, 運行阻塞性指令會阻塞檢測循環, 也不能進行同步的動作式函數

finish

action& finish(const std::function<void()> event);

設定結束事件, 函式會在動作停止後呼叫, 並且可以運行動作函式

forceStop

action& forceStop();

立即停止動作處理器並結束動作生命週期

startHandler

action startHandler(handler h, std::string key);

高級函數, 啟動動作處理器並設定處理器的唯一金匙

參數:
- h
  
  即將執行的處理器, 必須提供完整的生命週期, 詳情請查看處理器的建構及使用
- key
  
  處理器的唯一識別金匙,以文字而組成,多數為四個字
返回: action控制介面如果成功開始動作的生命週期

limitStart

void limitStart(int ms);

開始執行時間限制, 此動作會清空上一次的時間限制記錄

參數:
- ms
  
  限制時間

limitEnd

void limitEnd();

結束指令時間限制

isTimeup

bool isTimeup();

取得現在或上一次指令是否超過執行時間限制

返回: True 如果超過限制時間, 否則 False

wait

void wait(int ms);

暫停線程並等待所設定的時間(以毫秒為單位)
指令與pros::delay不同, wait指令會配合限時控制

參數:
- ms
  
  等待的時間

waitUntil

void waitUntil(const std::function<bool()> condition);

暫停線程並等待直至條件成立

參數:
- condition
  
  等待條件建構及使用

waitUntilAboveSettled

void waitUntilAboveSettled();

暫停線程並等待所有指令完成

LCD

format

char* format(const char* f, ...);

格式化字符串

參數:
- f
  
  格式化的字符串
- ...
  
  格式化字符串的可選參數列表
返回: 格式化的字符串

log

template <typename... Params>
void log(std::int16_t line, const char* fmt, Params... args);

在LCD屏幕上顯示格式化的字符串

參數:
- line
  
  顯示文字的行[0-7]
- fmt
  
  格式化的字符串
- ...
  
  格式化字符串的可選參數列表

clearLog

void clearLog();

清空LCD屏幕上的所有內容

waitScreenBtnPress

uint8_t waitScreenBtnPress();

等待直至 LCD屏幕的按鈕狀態發生變化

返回: 新的按鈕狀態位掩碼

isLeftBtnPress

uint8_t isLeftBtnPress();

返回屏幕左側按鈕是否被按下

返回: 位掩碼 > 0 如果正在按下

isCenterBtnPress

uint8_t isCenterBtnPress();

返回屏幕中間按鈕是否被按下

返回: 位掩碼 > 0 如果正在按下

isRightBtnPress

uint8_t isRightBtnPress();

返回屏幕右側按鈕是否被按下

返回: 位掩碼 > 0 如果正在按下

initLCD

void initLCD();

初始化LCD屏幕

Move

配置

變數初始化

type	name	detail
PID	pidMove	直行指令使用平衡輪差距 PID 控制類
PID	pidLF	直行指令使用左前輪 PID 控制類
PID	pidRF	直行指令使用右前輪 PID 控制類
PID	pidTurnNear	轉彎指令短距離 PID 控制類
PID	pidTurnFar	轉彎指令長距離 PID 控制類
double	leftMargin	向左轉偏移加成
double	rightMargin	向右轉偏移加成

馬達與感應器

type	name	detail
Motor	mtrLeftF	左前輪
Motor	mtrLeftR	左後輪
Motor	mtrRightF	右前輪
Motor	mtrRightR	右後輪
int	portGyro	陀螺儀

angle_detection_sensor_e

此枚舉定義了不同種類的檢測角度感應器

Enum
GYRO	0
ENCODER	1

initMove

void initMove();

初始化移動指令

resetMove

void resetMove();

重設移動指令

drive

action drive(const float cm,
             const short lfspeed, const short lrspeed,
             const short rfspeed, const short rrspeed,
             const action_brake_mode_e_t brakemode = HOLD,
             int tick = 0);

向前直行一定距離, 然後停止

參數:
- cm
  
  移動距離, 厘米, 不能負數
- lfspeed
  
  左前輪子的馬達速度, 範圍 -127 ~ +127
- lrspeed
  
  左後輪子的馬達速度, 範圍 -127 ~ +127
- rfspeed
  
  右前輪子的馬達速度, 範圍 -127 ~ +127
- rrspeed
  
  右後輪子的馬達速度, 範圍 -127 ~ +127
- brakemode
  
  設定馬達停止後的制動方式, 可選, 預設為 HOLD
- tick
  
  移動距離(單位tick), 可選, 預設為 0
  
  不填寫 : 距離跟從cm, 並由cm計算出實際移動多少tick
  
  填寫 : 覆蓋cm, 不能負數
返回: action結構以控制指令

forward

action forward(const float cm,
               const short speed = 0,
               const action_brake_mode_e_t brakemode = HOLD,
               int tick = 0);

向前直行一定距離, 然後停止

參數:
- cm
  
  移動距離(單位厘米), 不能負數
- speed
  
  輪子的馬達速度, 可選, 預設為 0
  
  不填寫 : 由PID運算控制
  
  填寫 : 範圍 +1 ~ +127
- brakemode
  
  設定馬達停止後的制動方式, 可選, 預設為 HOLD
- tick
  
  移動距離(單位tick), 可選, 預設為 0
  
  不填寫 : 距離跟從cm, 並由cm計算出實際移動多少tick
  
  填寫 : 覆蓋cm, 不能負數
返回: action結構以控制指令

backward

action backward(const float cm,
                const short speed = 0,
                const action_brake_mode_e_t brakemode = HOLD,
                int tick = 0);

向後直行一定距離, 然後停止

參數:
- cm
  
  移動距離(單位厘米), 不能負數
- speed
  
  輪子的馬達速度, 可選, 預設為 0
  
  不填寫 : 由PID運算控制
  
  填寫 : 範圍 +1 ~ +127
- brakemode
  
  設定馬達停止後的制動方式, 可選, 預設為 HOLD
- tick
  
  移動距離(單位tick), 可選, 預設為 0
  
  不填寫 : 距離跟從cm, 並由cm計算出實際移動多少tick
  
  填寫 : 覆蓋cm, 不能負數
返回: action結構以控制指令

turnLeftToAzimuth

action turnLeftToAzimuth(const float angle, 
                         const short speed = 0, 
                         const double error = 1);

轉左到指定的絕對方位角並停下, 無論轉右到達目標是否近於轉左到達
絕對方位角是指自動程式開始時機械人面向角與現時機械人面向角之間的角度差

參數:
- angle
  
  絕對方位角(單位角度)
- speed
  
  轉向的馬達速度, 可選, 預設為 0
  
  不填寫 : 由PID運算控制
  
  填寫 : 範圍 +1 ~ +127
- error
  
  判斷動作完成的誤差的容許範圍(單位角度)
返回: action結構以控制指令

turnRightToAzimuth

action turnRightToAzimuth(const float angle,
                          const short speed = 0,
                          const double error = 1);

轉右到指定的絕對方位角並停下, 無論轉左到達目標是否近於轉右到達
絕對方位角是指自動程式開始時機械人面向角與現時機械人面向角之間的角度差

參數:
- angle
  
  絕對方位角(單位角度)
- speed
  
  轉向的馬達速度, 可選, 預設為 0
  
  不填寫 : 由PID運算控制
  
  填寫 : 範圍 +1 ~ +127
- error
  
  判斷動作完成的誤差的容許範圍(單位角度)
返回: action結構以控制指令

turnLeft

action turnLeft(const float angle, 
                const short speed = 0, 
                const double error = 1,
                const angle_detection_sensor_e_t sensor = GYRO);

轉左指定角度並停下

參數:
- angle
  
  轉左的角度(單位角度)
- speed
  
  轉向的馬達速度, 可選, 預設為 0
  
  不填寫 : 由PID運算控制
  
  填寫 : 範圍 +1 ~ +127
- error
  
  判斷動作完成的誤差的容許範圍(單位角度)
- sensor
  
  檢測角度的感應器種類
返回: action結構以控制指令

turnRight

action turnRight(const float angle, 
                 const short speed = 0, 
                 const double error = 1,
                 const angle_detection_sensor_e_t sensor = GYRO);

轉右指定角度並停下

參數:
- angle
  
  轉右的角度(單位角度)
- speed
  
  轉向的馬達速度, 可選, 預設為 0
  
  不填寫 : 由PID運算控制
  
  填寫 : 範圍 +1 ~ +127
- error
  
  判斷動作完成的誤差的容許範圍(單位角度)
- sensor
  
  檢測角度的感應器種類
返回: action結構以控制指令

keepMove

action keepMove(const short lfspeed, const short lrspeed,
                const short rfspeed, const short rrspeed,
                const int waitms = 0);

指定不同馬達速度

參數:
- lfspeed
  
  左前輪子的馬達速度, 範圍 -127 ~ +127
- lrspeed
  
  左後輪子的馬達速度, 範圍 -127 ~ +127
- rfspeed
  
  右前輪子的馬達速度, 範圍 -127 ~ +127
- rrspeed
  
  右後輪子的馬達速度, 範圍 -127 ~ +127
- waitms
  
  持續毫秒, 可選, 預設為 0
  
  不填寫 : 持續
  
  填寫 : 持續ms毫秒, 然後停止
返回: action結構以控制指令

keepMove

action keepMove(const short lspeed, const short rspeed, const int waitms = 0);

指定左方及右方馬達速度

參數:
- lspeed
  
  左輪子的馬達速度, 範圍 -127 ~ +127
- rspeed
  
  右輪子的馬達速度, 範圍 -127 ~ +127
- waitms
  
  持續毫秒, 可選, 預設為 0
  
  不填寫 : 持續
  
  填寫 : 持續ms毫秒, 然後停止
返回: action結構以控制指令

holdMove

action holdMove(const bool isenable = true);

保持輪子馬達位置, 此動作不阻塞線程

參數:
- isenable
  
  是否保持, 可選, 預設為 True
返回: action結構以控制指令

Roller

配置

馬達與感應器

type	name	detail
Motor	mtrRoller	滾筒

roller

action roller(const short speed, const int waitms = 0);

指定滾筒馬達速度

參數:
- speed
  
  滾筒的馬達速度, 範圍 -127 ~ +127
- waitms
  
  持續毫秒, 可選, 預設為 0
  
  不填寫 : 持續
  
  填寫 : 持續ms毫秒, 然後停止
返回: action結構以控制指令

Shooter

配置

變數初始化

type	name	detail
int	msShootTime	保持/基準位置到釋放位置所需時間
int	msBackTime	釋放位置到基準位置所需時間
int	msHoldTime	基準位置到保持位置所需時間

馬達與感應器

type	name	detail
Motor	mtrShooter	發射器

arm

action shooter();

射擊一次並回到準備點

返回: action結構以控制指令

FilesExpand file tree

api-document.md

Latest commit

History

api-document.md

File metadata and controls

API Document

#define

limit

lamdba

await

redonly

blueonly

waiting

Arm

配置

馬達與感應器

arm

Config

loadConfig

saveConfig

Core

action_brake_mode_e

action_component_type_e

handler

fnc_update_

fnc_loop_

fnc_stop_

compare_operator_

start_value_

start_time_

waituntil_value_

waituntil_time_

thread_run_

fnc_event_to_

fnc_event_finish_

action

id_

enable_wait_until_

awaitUntil

to

finish

forceStop

startHandler

limitStart

limitEnd

isTimeup

wait

waitUntil

waitUntilAboveSettled

LCD

format

log

clearLog

waitScreenBtnPress

isLeftBtnPress

isCenterBtnPress

isRightBtnPress

initLCD

Move

配置

變數初始化

馬達與感應器

angle_detection_sensor_e

initMove

resetMove

drive

forward

backward

turnLeftToAzimuth

turnRightToAzimuth

turnLeft

turnRight

keepMove

keepMove

holdMove

Roller

配置

馬達與感應器

roller