docs: add code comment

Author: BoBoDai

docs/src/installation_and_configuration.md

@@ -65,4 +65,34 @@ control_mode: inverse # inverse, act 行动模式
 - port：在安装lerobot后，处于lerobot环境下，将设备连接到电脑运行`lerobot-find-port`,之后会出现一堆设备号，根据指示，拔掉连接线后按回车，即可获得串口号，控制板上的环境已经安装完毕，端口号为固定的 '/dev/ttyACM0'
 - hardware_mode: 在PC上调试的时候选择normal模式，在控制板上运行的时候，为rk3588
 
+## 首次运行
+
+#### 机械臂初始设置
+
+连接机械臂后首次运行代码，由于没有硬件配置文件，需要初始化机械臂
+
+正常会看见
+```
+"Move robot to the middle of its range of motion and press ENTER...."
+```
+之后将所有电机置于中点位置，按回车，之后缓慢的转动所有电机，到每个电机的上下限位，之后按回车，即可完成配置文件的录入。
+
+#### 项目再次启动
+
+如果已经生成配置文件，打开项目能看到
+
+```
+"Press ENTER to use provided calibration file associated with the id {self.id}, or type 'c' and press ENTER to run calibration: "
+```
+
+之后可以按ENTER进入项目，或者等待3秒进入项目，或者输入c + ENTER重新初始化。
+
+配置文件路径为
+
+```
+~/.cache/huggingface/lerobot/calibration/robots/lekiwi/None.json
+```
+
+删除它后进入项目自动进入初始化模式
+
 ## 硬件连接设置

src/main.py

@@ -20,16 +20,17 @@
 logger = logging.getLogger(__name__)
 logging.basicConfig(level=getattr(logging, get_log_level()))
 
-CATCH_ACTION = [("shoulder_pan", -11),
-                ("gripper", 50),
-                ("wrist_flex", 88),
-                ("move_to", (0.0750, 0.1211)),
-                ("move_to", (0.0750, -0.04)),
-                ("gap", 0),
-                ("gripper", -40),
-                ("shoulder_pan", 11),
-                ("move_to", (0.07, 0.24)),
-                ("wrist_flex", 8)
+# 夹球的动作序列
+CATCH_ACTION = [("shoulder_pan", -11), # 对应1号舵机
+                ("gripper", 50), # 夹爪打开
+                ("wrist_flex", 88),  # 腕部舵机转动角度
+                ("move_to", (0.0750, 0.1211)), # 机械臂坐标移动指令，x移动到范围为 0.22 - -0.22
+                ("move_to", (0.0750, -0.04)), # 机械臂移动到球的位置， y移动范围为 0.22 - -0.15
+                ("gap", 0), # 停顿指令
+                ("gripper", -40), # 夹爪关闭
+                ("shoulder_pan", 11), # 1号舵机归位
+                ("move_to", (0.07, 0.24)), # 把球举起
+                ("wrist_flex", 8) # 腕部配合移动
                 ]
 
 
@@ -46,14 +47,14 @@ def main():
     for key, value in start_obs.items():
         if key.endswith('.pos'):
             motor_name = key.removesuffix('.pos')
-            start_positions[motor_name] = int(value)  # Don't apply calibration coefficients
+            start_positions[motor_name] = int(value)
 
     print("Initial joint angles:")
     for joint_name, position in start_positions.items():
         print(f"  {joint_name}: {position}°")
 
-    return_to_start_position(robot, start_obs, get_target_positions(), 0.9, get_fps())
-    x0, y0 = 0.0989, 0.125
+    return_to_start_position(robot, start_obs, get_target_positions(), 0.9, get_fps()) # 机械臂回到预设位置
+    x0, y0 = 0.0989, 0.125 # 当前位置的xy坐标
     current_x, current_y = x0, y0
     command_step = 0
     try:
@@ -63,11 +64,11 @@ def main():
             current_obs = robot.get_observation()
             frame = current_obs["front"]
             if get_robot_status() == RobotStatus.FIND_BUCKET:
-                result = get_red_bucket_local(frame)
+                result = get_red_bucket_local(frame) # 找桶的算法
             else:
-                result = yolo_infer(frame)
+                result = yolo_infer(frame) # 找球的算法
 
-            if get_hardware_mode() == 'normal':
+            if get_hardware_mode() == 'normal': # 摄像头视角显示，
                 for box in result:
                     x, y, w, h = box.x, box.y, box.w, box.h
                     center_x = x + w // 2

src/move_controller.py

@@ -28,31 +28,31 @@ def move_controller(direction: DirectionControl, result: list[Box]) -> dict[str,
         center_x = x + w // 2
         position = max(w, h)
         _last_ball_center_x = center_x
-        if center_x < left:
-            if abs(TARGET_CX - center_x) < target_w * 1.5:
+        if center_x < left: # 如果球位于目标框左侧
+            if abs(TARGET_CX - center_x) < target_w * 1.5: # 球与目标框中点距离小于目标框的1.5倍，慢速前进
                 action = direction.get_action("rotate_left", 0)
             else:
                 action = direction.get_action("rotate_left")
             _cycle_time = 0
-        elif center_x > right:
-            if abs(TARGET_CX - center_x) < target_w * 1.5:
+        elif center_x > right: # 如果球位于目标框右侧
+            if abs(TARGET_CX - center_x) < target_w * 1.5: # 与目标框中点距离小于目标框的1.5倍，慢速前进
                 action = direction.get_action("rotate_right", 0)
             else:
                 action = direction.get_action("rotate_right")
             _cycle_time = 0
-        elif position < (TARGET_POSITION - 8) * 2:
+        elif position < (TARGET_POSITION - 8) * 2: # 如果球在摄像头中的直径小于，目标框-8的2倍 ，则前进（可调）
             if position * 2 > TARGET_POSITION:
                 action = direction.get_action("forward", 0)
             else:
                 action = direction.get_action("forward")
             _cycle_time = 0
-        elif position > (TARGET_POSITION + 10) * 2:
+        elif position > (TARGET_POSITION + 10) * 2: # 如果球在摄像头中的直径大于，目标框+10的2倍 ，则后退（可调）
             action = direction.get_action("backward", 0)
             _cycle_time = 0
         else:
             action = direction.get_action(None)
             _cycle_time += 1
-            if _cycle_time > 10:
+            if _cycle_time > 10: # 10帧稳定存在，则进入下一流程
                 set_robot_status(RobotStatus.PICK)
                 _cycle_time = 0
     else:
@@ -74,31 +74,31 @@ def move_controller_for_bucket(direction: DirectionControl, result: list[Box]) -
         center_x = x + w // 2
         position = min(w, h)
         _last_ball_center_x = center_x
-        if center_x < left:
+        if center_x < left: # 如果桶位于目标框左侧
             if abs(TARGET_CX - center_x) < target_w:
                 action = direction.get_action("rotate_left", 0)
             else:
                 action = direction.get_action("rotate_left")
             _cycle_time = 0
-        elif center_x > right:
+        elif center_x > right: # 如果桶位于目标框右侧
             if abs(TARGET_CX - center_x) < target_w:
                 action = direction.get_action("rotate_right", 0)
             else:
                 action = direction.get_action("rotate_right")
             _cycle_time = 0
-        elif position < TARGET_POSITION * 2.6:
-            if TARGET_POSITION - position < target_h:
+        elif position < TARGET_POSITION * 2.6: # 如果桶在摄像头中的直径小于目标框的2.6倍，则前进
+            if TARGET_POSITION - position < target_h: # 保证快速前进，if可以去掉
                 action = direction.get_action("forward")
             else:
                 action = direction.get_action("forward")
             _cycle_time = 0
-        elif position > TARGET_POSITION * 3:
+        elif position > TARGET_POSITION * 3: # 如果桶在摄像头中的直径大于目标框的3倍，则后退
             action = direction.get_action("backward", 0)
             _cycle_time = 0
         else:
             action = direction.get_action(None)
             _cycle_time += 1
-            if _cycle_time > 10:
+            if _cycle_time > 10: # 10帧稳定存在，则进入下一流程
                 set_robot_status(RobotStatus.PUT_BALL)
                 _cycle_time = 0
     else:

src/setup.py

@@ -4,10 +4,10 @@
 
 
 class RobotStatus(Enum):
-    SEARCH = "search"
-    PICK = "pick"
-    FIND_BUCKET = "find_bucket"
-    PUT_BALL = "put_ball"
+    SEARCH = "search" # 找球模式
+    PICK = "pick" # 捡球模式
+    FIND_BUCKET = "find_bucket" # 找桶模式
+    PUT_BALL = "put_ball" # 放球模式
 
 
 class RobotControlModel(Enum):