diff --git a/sources/2890/canjector-endz-render.png b/sources/2890/canjector-endz-render.png new file mode 100644 index 0000000..d11b19b Binary files /dev/null and b/sources/2890/canjector-endz-render.png differ diff --git a/sources/2890/canjector-middle-schematic.png b/sources/2890/canjector-middle-schematic.png new file mode 100644 index 0000000..7ebd43f Binary files /dev/null and b/sources/2890/canjector-middle-schematic.png differ diff --git a/sources/2890/canjector-minor-render.png b/sources/2890/canjector-minor-render.png new file mode 100644 index 0000000..2fbd92f Binary files /dev/null and b/sources/2890/canjector-minor-render.png differ diff --git a/sources/play/esp32-gpio-mapping.md b/sources/play/esp32-gpio-mapping.md new file mode 100644 index 0000000..8d7db25 --- /dev/null +++ b/sources/play/esp32-gpio-mapping.md @@ -0,0 +1,103 @@ +--- +title: "M5Stack Core ESP32 GPIO Pinout Reference" +tags: + - esp32 + - m5stack + - gpio + - pinout + - hardware + - play +type: hardware-spec +owner: play +status: active +sources: + - "https://www.espboards.dev/esp32/m5stack-core-esp32/" + - "https://docs.m5stack.com/en/mpy/official/machine" + - "https://github.com/m5stack/m5-docs/issues/175" +--- + +# M5Stack Core ESP32 GPIO Pinout Reference + +## Physical GPIO Ranges + +Available pins: **0-19, 21-23, 25-27, 32-39** + +These correspond to actual ESP32 GPIO pin numbers. Many boards use their own logical pin numbering (D0, D1, etc.) — this doc maps logical to physical. + +## Reserved Pins (Do Not Use for Custom I/O) + +| Pin | Reserved For | Notes | +|-----|--------------|-------| +| 0 | Boot / Button | Pulldown at boot — unsafe for output | +| 1 | TX0 | Debug serial | +| 2 | Boot / Button | Pulldown at boot | +| 3 | RX0 | Debug serial | +| 6-11 | Flash SPI | Internal flash memory — do not use | +| 12 | Boot / GPIO | Pulldown at boot — unsafe for output | +| 18, 19, 23 | SPI (LCD + TF Card) | Shared with display and SD card | +| 25 | Speaker | Connected to internal speaker amplifier | +| 21, 22 | I2C (Grove port) | SDA/SCL — available if Grove not used | + +## Safe GPIO for Custom Use + +| Pin | Safe Use | Notes | +|-----|----------|-------| +| 4 | General I/O | Safe if speaker not used | +| 5 | General I/O | Safe | +| 13 | General I/O | Safe | +| 14 | General I/O | Safe | +| 15 | General I/O | Safe (also MTDO) | +| 16 | General I/O | Safe | +| 17 | General I/O | Safe | +| 26 | Analog input | 12-bit ADC (also digital I/O) | +| 27 | Analog input | 12-bit ADC (also digital I/O) | +| 32-39 | Analog input | 12-bit ADC — best for sensor readings | + +## I2C Bus (Grove Port) + +- **SDA:** GPIO 21 +- **SCL:** GPIO 22 + +If Grove port is not in use, pins 21/22 are available as general GPIO. + +## SPI Bus + +Default SPI (for LCD + SD card): GPIO 18 (CLK), 19 (MISO), 23 (MOSI). These are shared — using them for other devices may conflict with display. + +Second SPI available on other pins if needed. + +## Communication Protocols + +- **UART:** TX on GPIO 1, RX on GPIO 3. Can remap to other pins. +- **I2C:** Default on 21/22. Can remap with `machine.SoftI2C` +- **SPI:** Default on 18/19/23. Can remap with `machine.SPI` + +## Analog (ADC) + +ESP32 has two ADC units: +- **ADC1:** pins 32-39 (best for sensors) +- **ADC2:** pins 0, 2, 4, 12-15 (conflicts with WiFi) + +12-bit resolution (0-4095). Max input: 3.3V. + +## For Chris's Projects + +Based on typical M5Stack setups: +- **Grove connectors** use I2C (21/22) — leave available if using Grove sensors +- **Display conflict** means 18/19/23 are unavailable in most setups +- **Speaker on 25** — disable speaker if you need that pin +- **Analog sensors** (temperature, pressure, gas) work well on 32-39 + +## Common Pinouts for Chris's Projects + +| Project | Pins Used | Notes | +|---------|-----------|-------| +| TILT replacement (I2C sensor) | 21 (SDA), 22 (SCL), 3.3V, GND | Uses Grove I2C | +| OLED display (I2C) | 21 (SDA), 22 (SCL) | 0.96" SSD1306 typical | +| Stepper motor (ULN2003) | Any safe GPIO x 4 | 4 control pins | +| Servo | GPIO 4 or 5 | 50Hz PWM | +| DS18B20 temp sensor | Any GPIO (1-wire) | Single wire + pullup | + +--- +*Research from web search — ESP32 GPIO mapping for M5Stack Core* +*Queue: research complete — moved to wiki* \ No newline at end of file diff --git a/training/modules/gear-ratio-mechanism-design.md b/training/modules/gear-ratio-mechanism-design.md new file mode 100644 index 0000000..bf929a4 --- /dev/null +++ b/training/modules/gear-ratio-mechanism-design.md @@ -0,0 +1,189 @@ +--- +title: "Choosing Gear Ratios for FRC Mechanisms" +tags: + - gear ratio + - mechanism + - design + - motor + - torque + - speed + - frc + - 2890 +type: training-module +owner: 2890 +status: active +sources: + - "https://docs.wcproducts.com/frc-build-system/belts-chain-and-gears/gears" + - "https://www.frcdesign.org/learning-course/stage1/1B/torque-speed/" + - "https://blog.thebluealliance.com/2013/06/24/behind-the-design-understanding-motor-and-gearbox-design/" +--- + +# Choosing Gear Ratios for FRC Mechanisms + +## Core Principle + +**Speed and torque are inversely proportional.** A 4:1 gear reduction gives you 4× the torque but 1/4 the speed. + +``` +Gear Ratio = Driven Gear Teeth / Driver Gear Teeth + +If ratio = 4:1 (input:output = 1:4): + Torque → multiplied by 4 + Speed → divided by 4 +``` + +## The Design Process + +### Step 1: Define Your Goal + +Ask these questions: +- What does this mechanism need to **do**? +- How **fast** does it need to move? +- How **heavy** is the load? +- What's the **time constraint** (game-specific)? + +### Step 2: Calculate Required Output + +For each mechanism: + +| Mechanism | Key Metric | Typical Range | +|-----------|------------|---------------| +| Drivetrain | Top speed | 10-15 ft/s | +| Elevator | Lift speed | 3-6 ft/s | +| Arm | Rotation speed | 90-180°/sec | +| Intake | Roll speed | Fast (1-2 sec) | +| Shooter | RPM | 3000-6000 RPM | + +### Step 3: Match Motor to Load + +**NEO Vortex specs (Team 2890's standard):** +- Free speed: 6784 RPM +- Stall torque: 3.6 Nm (0.36 kg·m) +- Peak output: 640W +- Continuous (40A): ~375W + +**Work backward from desired output speed:** +``` +Required output speed = X RPM +↓ +Account for mechanism reduction (belts, chains, gears) +↓ +Calculate motor speed needed +↓ +Find gear ratio +``` + +## Drivetrain Gear Ratio Selection (Team 2890) + +Team 2890 uses **L1 and L3** on MK4i modules with NEO Vortex: + +| Ratio | Speed | Torque | Use When | +|-------|-------|--------|----------| +| **L1** (8.14:1) | ~14.4 ft/s | Lower | High speed needed, less pushing | +| **L3** (6.12:1) | ~12.8 ft/s | Higher | More pushing power, climbing | + +**L1 = faster, less torque. L3 = slower, more torque.** + +Swap based on game demands. Field-swappable. + +## Mechanism Design Guidelines + +### Elevators / Vertical Motion + +``` +Motor → Belt reduction → Sprocket → Chain → Carriage +``` + +- Target: 3-6 ft/s vertical +- Common ratios: 4:1 to 10:1 per stage +- Watch for staging — two-stage elevators need compounding reduction + +### Arms / Swing Motion + +``` +Motor → Gearbox → Arm +``` + +- Target: 90-180°/sec rotation +- Consider start-up torque (gravity fight at low angle) +- PID control essential for repeatable positioning + +### Shooters / Flywheels + +``` +Motor → Gearbox → Wheel +``` + +- Target: 3000-6000 RPM wheel speed +- High reduction = more torque at wheel, faster spin-up +- Common ratio: 3:1 to 5:1 + +### Intake Rollers + +``` +Motor → Direct or light reduction → Roller +``` + +- Target: Fast roll-in (under 2 seconds) +- Low reduction or direct drive works +- Rubber roller = good grip, no gear reduction needed + +## Motor Sizing Rules of Thumb + +1. **Stall torque > Load torque at worst angle** +2. **Free speed > Desired output speed by 2× minimum** +3. **Current draw at stall < 80% of breaker rating** +4. **Continuous torque > Average load torque** + +## Common FRC Motor/Gearbox Pairings + +| Motor | Typical Gearbox | Output | Use | +|-------|----------------|--------|-----| +| NEO Vortex | Built-in 4:1 | 1696 RPM | Drivetrain, mechanisms | +| NEO Vortex + planetary | External reduction | Variable | Elevators, arms | +| Falcon 500 | Integrated | 1680 RPM | Drivetrain, high torque | +| Kraken X60 | Integrated | ~1680 RPM | Newer alternative to Falcon | + +## The Calculation + +``` +Desired output RPM = X +Motor free RPM = 6784 (NEO Vortex) +Total reduction needed = 6784 / X + +Example: Want 600 RPM output + 6784 / 600 = 11.3:1 reduction needed + +Split across stages: + Stage 1 (belt): 3:1 + Stage 2 (gearbox): 4:1 + Total = 12:1 — close to target +``` + +## Signs You've Got It Wrong + +- **Too fast / not enough torque:** Robot stalls under load, wheels slip +- **Too slow / too much torque:** Mechanism moves too slowly to be useful +- **Motor overheating:** Too much load for continuous operation — need more reduction or bigger motor +- **Brownouts:** Current spikes from stalling — check breaker sizing + +## For Team 2890 Students + +When designing a mechanism: +1. **Define the task** — what does it need to do in the game? +2. **Pick the motor** — NEO Vortex is standard on 2890 +3. **Calculate the speed you need** — game constraints (time limits, field size) +4. **Work backward** — gear ratio = motor speed / desired output speed +5. **Split across stages** — belt + gearbox is easier than single-stage high ratio +6. **Test and tune** — PID tuning can fix some speed issues, but wrong gear ratio can't be fixed with software + +## Related + +- [[swere-modules]] — MK4i gear options for drivetrain +- [[neo-vortex-motor]] — motor specs +- [[spark-flex]] — controller configuration +- [[motor-basics]] — understanding motor curves + +--- +*Research from web search — gear ratio design for FRC mechanisms* +*Queue: research complete — stored in wiki* \ No newline at end of file diff --git a/training/modules/megatag.md b/training/modules/megatag.md new file mode 100644 index 0000000..11de7c9 --- /dev/null +++ b/training/modules/megatag.md @@ -0,0 +1,119 @@ +--- +title: "MegaTag — Robot Localization with AprilTags" +tags: + - megatag + - apriltag + - vision + - localization + - limelight + - photonvision + - odometry + - frc + - 2890 +type: training-module +owner: 2890 +status: active +sources: + - "https://docs.limelightvision.io/docs/docs-limelight/pipeline-apriltag/apriltag-robot-localization" + - "https://docs.yagsl.com/fundamentals/swerve-drive" +--- + +# MegaTag — Robot Localization with AprilTags + +## What Is MegaTag? + +MegaTag is a **Limelight-specific** robot localization system that uses AprilTags + IMU (gyro) data to determine the robot's position on the field. It's not a Limelight-only concept — similar approaches exist with PhotonVision + WPILib pose estimators — but "MegaTag" specifically refers to Limelight's implementation. + +**Key point:** Team 2890 uses **PhotonVision**, not Limelight. MegaTag documentation is useful for understanding the **concept** of vision-based odometry fusion, but the implementation uses PhotonVision's pose estimator + WPILib's `SwerveDrivePoseEstimator`. + +## MegaTag vs. MegaTag2 + +| Feature | MegaTag 1 | MegaTag 2 | +|---------|-----------|-----------| +| Data source | AprilTag vision only | AprilTag + IMU fusion | +| Accuracy | Good when tags visible | Better — gyro corrects drift | +| Drift | Accumulates over time | Reduced by gyro correction | +| Tag visibility required | Yes | Yes (but less sensitive) | + +**MegaTag 2** fuses robot orientation data from the IMU with vision pose. This means even if vision is slightly noisy or a tag is partially visible, the gyro steadies the reading. + +## How It Works (Conceptual) + +``` +AprilTag camera → Robot pose (x, y, rotation) + ↓ +Gyro heading → Corrections / steadying + ↓ +Pose Estimator → Combines: + - Wheel odometry (always drifting) + - Vision pose (accurate but intermittent) + ↓ +Final robot position (fused) +``` + +## For Team 2890 (PhotonVision) + +Team 2890 runs PhotonVision on Raspberry Pi, AprilTags on the field. The equivalent fusion happens in WPILib: + +```java +// SwerveDrivePoseEstimator fuses: +// 1. Wheel odometry (always running, drifts) +// 2. Vision measurements (accurate when tags visible) + +SwerveDrivePoseEstimator estimator = new SwerveDrivePoseEstimator( + kinematics, + gyro.getRotation2d(), // IMU heading + modulePositions, // wheel encoders + new Pose2d(x, y, rotation) // initial estimate +); + +// Add vision measurement when tag visible: +estimator.addVisionMeasurement( + photonPoseEstimator.getEstimatedPosition(), + Timer.getFPGATimestamp() +); +``` + +## The Key Concept for Students + +**Robot localization = knowing where you are on the field.** + +AprilTags give you a reference point. The gyro gives you orientation. Fusing them gives you accurate, stable position tracking even when: +- Only one tag is visible +- Tags are partially obscured +- Robot is moving fast + +This is critical for: +- Autonomous paths that need to return to same spot +- Field-relative driving with joystick +- Score estimation / match strategy + +## Common Issues and Troubleshooting + +| Problem | Likely Cause | Fix | +|---------|--------------|-----| +| Pose always offset in same direction | Camera calibration wrong | Check camera tilt, height, direction | +| Pose jumps when tag visible | Vision trusting single reading | Add filtering, check timing | +| No pose when tags visible | Camera not processing tags | Check PhotonVision pipeline | +| Odometry drifts despite vision | Vision not being added to estimator | Check `addVisionMeasurement` call | +| Gyro disagrees with vision | Gyro calibration issue | Re-calibrate gyro, check wiring | + +## Connection to Training + +For students learning swerve odometry: +1. **Wheel odometry** — always tracking, always drifting +2. **Vision pose** — accurate when AprilTags visible +3. **Pose estimator** — fuses both for best of both worlds +4. **Field constants** — AprilTag positions, field dimensions must be correct + +The MegaTag concept (vision + gyro fusion) is the same regardless of whether you use Limelight or PhotonVision. Understanding it helps students debug pose estimation issues. + +## Related + +- [[photonvision]] — Team 2890's vision system +- [[swere-modules]] — MK4i with encoders for odometry +- [[systemcore]] — upcoming controller with improved processing + +--- +*Research from web search — MegaTag concept for FRC vision localization* +*Queue: research complete — stored in wiki* \ No newline at end of file