3.1 Arm Control System

3.1.1 Objectives

• Driver-friendly arm control via physical controllers.
• Accurate/safe motion via inverse kinematics (IK).
• Validate in simulation (RViz/Gazebo) before hardware.

3.1.2 Functional Requirements

FR-1.1 Simulation & Testing

• FR-1.1.1 URDF loads in RViz; Gazebo optional for physics/collision.
• FR-1.1.2 Validate teleop, IK, limits in simulation before hardware.
• FR-1.1.3 Simulation Readiness Gate:
  • Multi-pose script completes without errors/self-collisions.
  • No joint exceeds velocity/accel limits (tiny numerical overshoot allowed).
  • E-Stop response ≤ 0.5 s (latched until cleared).
  • Watchdog: if no /arm/cmd_* ≥ 0.2 s → zero velocity + warning.
• FR-1.1.4 Support End-Effector mode (IK) and Joint mode (per-joint).

FR-1.2 Controller Integration

• FR-1.2.1 Logitech Extreme 3D Pro as primary input.
• FR-1.2.2 Topics/messages:

Function	Topic	Message Type (suggestion)	Dir
End-Effector Command	/arm/cmd_ee	geometry_msgs/PoseStamped	In
Joint Command	/arm/cmd_joint	sensor_msgs/JointState or Float64MultiArray	In
Emergency Stop	/system/estop	std_msgs/Bool	In
Joint Feedback	/arm/joint_states	sensor_msgs/JointState	Out
Diagnostics	/diagnostics	diagnostic_msgs/DiagnosticArray	Out

• FR-1.2.3 HAL decouples controller logic from motor drivers (PWM/CAN/sim) via config.
• FR-1.2.4 On controller disconnect, neutralize all commands immediately.
• FR-1.2.5 Default mappings and modes defined in arm.yaml (see Appendix A).

FR-1.3 Inverse Kinematics (IK)

• FR-1.3.1 Support direct joint control and IK EE positioning.
• FR-1.3.2 Scripted positional error ≤ 5 cm; orientation error ≤ 5° (simulation).
• FR-1.3.3 Reject unreachable poses with clear operator message.

FR-1.4 Safety & Reliability

• FR-1.4.1 Hardware/software E-Stop halts all motion ≤ 0.5 s; latched until ~/clear_estop.
• FR-1.4.2 Enforce joint hard/soft limits, vel/acc caps at all times.
• FR-1.4.3 Watchdog: stop and raise diagnostic alert if command gap ≥ 0.2 s.
• FR-1.4.4 Publish mode/limit/errors to /diagnostics.

FR-1.5 Documentation & Configuration

• FR-1.5.1 Quick start, controller mapping reference, arm.yaml params, troubleshooting.
• FR-1.5.2 Version-control all configs/launch/mappings and standardize.

3.1.4 Non-Functional Requirements

ID	Type	Requirement
NFR-1.1	Performance	Controller input latency ≤ 1 s under normal operation.
NFR-1.2	Reliability	Operate ≥ 1 hour without restart.
NFR-1.3	Usability	Operator can perform standard tasks after ≤ 10 minutes of familiarization.
NFR-1.4	Testability	Automated rostest validates limits, E-Stop, watchdog; CI fails if checks fail.

3.1.5 Verification Criteria

• Simulation Readiness Gate passes.
• EE positional ≤ 5 cm; orientational ≤ 5°.
• E-Stop ≤ 0.5 s; watchdog triggers ≥ 0.2 s.
• Out-of-limit and disconnect behaviors correct.
• Documentation/config complete and reviewed; no overfitting to sim physics.