feat: added documentation for RoboticArm

tutorials/roboticarm.md

@@ -1,14 +1,130 @@
-Robotic Arm Servos
-======
+# Robotic Arm
 
-Introduction to motors
-----------------------
+## What is a Robotic Arm?
 
-Servos
-------
+A **Robotic arm** is a mechanical structure that mimics the movements of a human arm. It typically consists of multiple joints controlled by actuators most commonly, **servo motors** to achieve precise angular movement.
+
+In the PSLab context, a robotic arm uses servo motors to perform tasks like conducting scientific experiments,  lifting, rotating, or grasping. These servos are controlled via **PWM (Pulse Width Modulation)** signals.
+
+The **PSLab device** provides four square wave PWM outputs `SQR1`, `SQR2`, `SQR3`, and `SQR4` which allow control of up to **four servo motors**, enabling robotic arms with **up to four degrees of freedom (DoF)**.
+
+---
+
+## How to use it
+
+### Requirements
+
+- PSLab device  
+- Robotic arm kit 
+- Jumper wires
+- External power supply
+
+<div style="display: flex; justify-content: space-between; align-items: flex-start; flex-wrap: wrap; gap: 10px; margin: 10px 0;">
+  <img src="../images/pslab_wave_pins.png" alt="PSLab Wavegen Pins" style="height: 250px; object-fit: contain;">
+  <img src="../images/robotic_arm_kit.jpg" alt="Robotic Arm Kit" style="height: 250px; object-fit: contain;">
+  <img src="../images/sg90_servo.jpg" alt="Servo Motor" style="height: 150px; object-fit: contain;">
+  <img src="../images/jumper_wires.jpg" alt="Jumper Wires" style="height: 150px; object-fit: contain;">
+</div>
+
+
+### Wiring Setup
+
+1. Connect the **signal wires** (usually **yellow**) of the 4 servos to the PSLab device PWM outputs PINS: `SQR1`, `SQR2`, `SQR3`, and `SQR4`.
+2. Connect the **power wires** (usually **red**) of all servos to the **positive terminal** of an **external power supply**.
+3. Connect the **ground wires** (usually **black**) of all servos together to the **GND of the external power supply**.
+4. Finally, connect the **GND of the external power supply** to the **GND pin** of the **PSLab device** to complete the common ground.
+
+> ⚠️ **Important:** Do not power the servos directly from the PSLab device. Use an external regulated supply capable of handling the current requirements of all servos.
+
+
+### Performing the Experiment
+
+1. Open the **PSLab app** on your Phone.
+  <img src="../images/img_robotic_arm3.png">
+2. Navigate to **Robotic Arm**.
+3. Use the interface to:
+   - Manually move each servo using sliders.
+   - Create a timeline of servo movements.
+   - Play, pause, or reset the timeline.
+   - Change Frequency.
+   - Save or import movements using CSV files.
+
+<table>
+    <tr>
+        <td><img src="../images/img_robotic_arm1.png"></td>
+        <td><img src="../images/img_robotic_arm2.png"></td>
+    </tr>
+</table>
+
+  <div style="text-align: center;">
+      <a href="https://youtu.be/zZ33pp560KA?si=OruiWHxXW4BBUqOx" target="_blank">Video 1</a> &nbsp;&nbsp;&nbsp;&nbsp;
+      <a href="https://youtu.be/IFSByhxeXV4?si=CTsC6272dFxwbhG-" target="_blank">Video 2</a>
+    </div>
+
+
+### Timeline CSV Import/Export
+
+The PSLab app supports importing servo movement timelines from a **CSV file**, allowing interoperability with the **PSLab Python library**.
+
+#### Exporting Timeline using Python
+
+You can generate servo movement timelines using the `pslab-python` library and export them in CSV format for use in the PSLab app.
+
+Here's a minimal working example:
+
+```python
+from pslab import ScienceLab
+from pslab.external.motor import Servo, RoboticArm
+
+psl = ScienceLab()
+
+# Initialize servos on PWM outputs PINS
+base = Servo("SQ1", pwm_generator=psl.pwm_generator)
+shoulder = Servo("SQ2", pwm_generator=psl.pwm_generator)
+elbow = Servo("SQ3", pwm_generator=psl.pwm_generator)
+grip = Servo("SQ4", pwm_generator=psl.pwm_generator)
+
+# Create Robotic Arm instance
+arm = RoboticArm([base, shoulder, elbow, grip])
+
+# Define timeline: each row = [S1, S2, S3, S4] angles at 1s interval
+# Use None to keep a servo at the same angle as the previous step
+timeline = [
+    [None, 30, 45, 10],
+    [90, 30, 45, None],
+    [180, 30, 45, None],
+    [45, 60, 60, 20],
+    [None, 60, 60, 20],
+    [0, 90, 90, 30],
+    [90, 90, 90, 30],
+    [180, 90, 90, 30],
+    [90, 45, 45, 0],
+    [0, 30, 30, None],
+]
+
+# Run the timeline on the robotic arm
+# This will move each servo to the specified positions sequentially at 1-second intervals
+arm.run_schedule(timeline=timeline)
+
+# Export timeline to CSV for using in PSLab App
+arm.export_timeline_to_csv(
+    timeline=timeline,
+    folderpath=r"C:\path\to\folder"
+)
+
+# Import timeline from a CSV file
+timeline = arm.import_timeline_from_csv(filepath=r"\path\to\folder\filename.csv")
+
+```
+
+### Observations
+
+- Each servo will rotate to the angle specified in real time.
+- Timeline playback enables coordinated movement of all joints.
+
+### Applications
+
+- Pick-and-place mechanisms
+- Educational demos in robotics and automation
 
-Experiment: How to move servos with PSLab
------------------------------------------
 
-Experiment: The Robot Arm Kit
------------------------------