# VEXcode API Reference

> AI assistant routing file for all VEX robotics platforms. Fetch the per-platform llms.txt for full API details.
> Full API docs: https://api.vex.com

**CRITICAL: APIs are NOT interchangeable across platforms.** Always confirm platform and language before generating code.

---

## Platforms

| Platform | Languages | VS Code | Competition | llms.txt |
|---|---|---|---|---|
| VEX 123 | Blocks | ❌ | ❌ | https://api.vex.com/123/llms.txt |
| VEX GO | Blocks, Python | ❌ | ❌ | https://api.vex.com/go/llms.txt |
| VEX AIM | Blocks, Python | ✅ Python only | ❌ | https://api.vex.com/aim/llms.txt |
| VEX IQ (1st gen) | Blocks, C++ | ❌ | ✅ VIQRC | https://api.vex.com/iq1/llms.txt |
| VEX IQ (2nd gen) | Blocks, Python, C++ | ✅ Python + C++ | ✅ VIQRC | https://api.vex.com/iq2/llms.txt |
| VEX EXP | Blocks, Python, C++ | ✅ Python + C++ | ❌ | https://api.vex.com/exp/llms.txt |
| VEX V5 | Blocks, Python, C++ | ✅ Python + C++ | ✅ V5RC, VURC, VAIRC | https://api.vex.com/v5/llms.txt |
| VEX CTE | Blocks, Python | ✅ Python only | ❌ | https://api.vex.com/cte/llms.txt |
| VEX AIR | Blocks, Python | ✅ Python only | ❌ | https://api.vex.com/air/llms.txt |
| VEXcode VR | Blocks, Python | ❌ | ❌ | https://api.vex.com/vr/llms.txt |

- **C++ in VS Code:** V5, EXP, IQ (2nd gen) only. AIM, AIR, CTE are Python-only everywhere.
- **VS Code not supported:** GO, 123, VR, IQ (1st gen) (Pyodide-streaming, virtual, and legacy platforms).
- **Competition templates** (`autonomous` / `driver_control`) exist only on V5 (V5RC, VURC, VAIRC). IQ platforms have no auton/driver-control phase split — never generate competition scaffolding for IQ or any other non-V5 platform.
- **VEX IQ generations:** IQ (1st gen) and IQ (2nd gen) have different APIs — fetch the correct platform file. If a user says "VEX IQ" without specifying generation, ask — the majority will be 2nd gen but 1st gen is still in use.
- **Platform unspecified:** If the platform cannot be determined from context, ask before generating code. Do not assume V5 or any other platform.

---

## Execution Models

| Model | How it works | Platforms |
|---|---|---|
| On-device MicroPython | Code runs on the robot Brain; self-contained after download | AIM, IQ (2nd gen), EXP, V5 |
| Pyodide → Hardware | Python runs in browser, streams commands over Bluetooth/USB-C; computer must stay connected | 123, GO, CTE (standalone) |
| Python 3.12 on Controller → Hardware | Full Python runs on the AIR Controller; commands sent wirelessly to drone | AIR |
| Pyodide → Virtual | Python runs in browser, commands go to a Unity3D simulation; no physical hardware | VR |

---

## Hardware Quick Reference

| Platform | Smart Ports | 3-Wire | Physical Screen | VEXcode Console | Speaker | Built-in IMU | Audience |
|---|---|---|---|---|---|---|---|
| 123 | 0 (fixed) | 0 | ❌ | ✅ | ✅ | ✅ | Pre-K–Gr 2 |
| GO | 4 + 1 I2C | 0 | ❌ | ✅ | ❌ | ❌ | Gr 2–5 |
| AIM | 0 (fixed) | 0 | ✅ round touch | ✅ | ✅ | ✅ | Gr 4–8 |
| IQ (1st gen) | 12 | 0 | ✅ color w/buttons | ✅ | ✅ | ❌ | Gr 4–8 |
| IQ (2nd gen) | 12 | 0 | ✅ color w/buttons | ✅ | ✅ | ✅ | Gr 5–8 |
| EXP | 10 | 8 | ✅ color w/buttons | ✅ | ✅ | ✅ | Gr 8–12 |
| V5 | 21 | 8 | ✅ color touch | ✅ | ✅ | ❌ (external) | Gr 7–12 |
| CTE | Arm (USB-C) | 0 | ❌ | ✅ | ❌ | ❌ | CTE/HS |
| AIR | Drone | 0 | ✅ Controller LCD | ✅ | ✅ (Controller) | ✅ (drone) | Gr 6–12 |
| VR | Virtual | Virtual | Virtual | ✅ | Virtual | Virtual | Any |

Physical Screen = hardware display on the robot/controller. VEXcode Console = software print console in the IDE (`brain.print()` output). All platforms support console output even without a physical screen.

**Key hardware notes:**
- V5 needs an external Inertial Sensor (Smart Port) — no built-in IMU.
- **Only V5 and EXP have 3-Wire ports.** 3-Wire device classes (`TriPort`, `Bumper`, `AnalogIn`, `Encoder`, `Pneumatics`, etc.) do not exist on IQ (2nd gen), AIM, GO, 123, or CTE. Never generate 3-Wire device code for those platforms.
- V5 and EXP Smart Port motors/sensors are cross-compatible. IQ motors/sensors are a different form factor and are not compatible with V5/EXP hardware.
- GO's extra port is I2C-only for the Optical Sensor.
- **CTE routing:** Arm-only projects (standalone USB-C or with Signal Tower) → use CTE llms.txt. Projects using Workcell peripherals (Pneumatic Solenoid, Conveyor, etc.) → use EXP llms.txt, as those require an EXP Brain connected via Smart Cable.

---

## Coding Environments

### VEXcode (web, desktop, mobile)
- Web and desktop: all languages for that platform (Blocks, Python, C++)
- **Mobile: Blocks only** on all platforms — no Python, no C++, no Switch blocks
- Devices window auto-generates device constructor calls in a hidden config region
- Platform-specific helpers (`calibrate_drivetrain()`, `convertColorToString()`) only available in VEXcode, only when devices are configured in the Devices window

### VS Code Extension
- Python and C++ only — no Blocks, no Switch blocks, no Devices window
- Templates pre-generate project scaffolding (imports, Brain, competition structure where applicable) but **not** device-specific constructors — motors and sensors must be written manually
- VEXcode IDE helpers absent; C++ `waitUntil()` and `repeat()` macros (EXP/V5) absent
- Same underlying API as VEXcode — only scaffolding differs

### Switch Blocks (Blocks + Python hybrid)
Available in GO, IQ (2nd gen), EXP, V5, CTE. Six shapes — identical across all platforms:

| Shape | Purpose |
|---|---|
| Stack | Python statements |
| C Block | Loop/conditional header (`while`, `if`, `for`) |
| C Expandable | Multi-branch (`if`/`elif`/`else`) |
| Boolean | Returns True/False — fits hexagonal inputs |
| Reporter | Returns a number — fits oval inputs |
| Hat | Defines a Python function |

Requires exact Python syntax. Not available on mobile.

---

## Universal Python Rules

### Runtime capabilities by platform

| Capability | MicroPython (AIM, IQ (2nd gen), EXP, V5) | Pyodide (GO, 123, CTE, VR) | Python 3.12 (AIR) |
|---|---|---|---|
| `time.sleep()` | ❌ | ✅ (don't use) | ✅ (don't use) |
| `import threading` | ❌ | ✅ (don't use) | ✅ (don't use) |
| `import random` | ❌ | ✅ | ✅ |
| `import urandom` | ✅ auto-imported | ✅ auto-imported | ❌ |
| `import math` | ✅ auto-imported | ✅ auto-imported | ✅ auto-imported |
| f-strings, comprehensions | ✅ | ✅ | ✅ |
| numpy, pillow | ❌ | ❌ | ✅ AIR only |

**On every platform:** use `wait(time, MSEC/SECONDS)` for delays — never `time.sleep()`.

### Rules that apply everywhere

1. **Config region is read-only.** Code generated by the Devices window goes in a `#region VEXcode Generated Robot Configuration` block. Never modify, duplicate, or regenerate it. User code goes below.
2. **`wait()` not `time.sleep()`** — universal VEX timing function regardless of platform.
3. **Constants are identifiers, not strings.** `wait(1, SECONDS)` ✅ — `wait(1, "SECONDS")` ❌.
4. **Use `Thread(fn)` not `import threading`** — `threading` module unavailable on MicroPython; don't use it on any VEX platform.
5. **Don't re-import auto-imported modules.** `from vex import *`, `import math`, `import urandom` are already in the config region.
6. **Don't re-instantiate pre-configured objects.** `brain`, motors, sensors, drivetrain are created in the config region in VEXcode. In VS Code, the template handles `brain` and framework objects — add device constructors manually.
7. **Competition scaffolding on V5 only (V5RC, VURC, VAIRC).** Never generate `autonomous()` / `user_control()` / `Competition()` for IQ or any other platform.

---

## Cross-Platform Mistakes

| Mistake | Why it's wrong |
|---|---|
| `drivetrain.drive_for()` on AIM | AIM uses `robot.move_for(distance, angle)` — holonomic, angle-based |
| `robot.move_at()` on V5/IQ | V5/IQ use differential drive: `drivetrain.drive()` + `drivetrain.turn()` |
| `brain.screen.print()` on AIM | AIM uses `robot.screen.print()` — no separate brain object |
| `Motor(Ports.PORT1)` on AIM | AIM is pre-configured — no manual device construction |
| Ground robot commands on AIR | AIR is a drone: `takeoff`, `land`, `fly`, `hover` — not `drive`/`turn` |
| V5 sensors on IQ or vice versa | IQ hardware is incompatible with V5/EXP sensors and motors |
| AI Vision on AIR | AIR cameras do AprilTag decoding only — no AI classification |
| CTE standalone API in Brain mode | Arm-only = CTE file. Workcell peripherals (Pneumatic, Conveyor) = EXP file — they require an EXP Brain |
| `Arm(Ports.PORT1)` in CTE standalone | Standalone CTE Arm takes no port: `Arm()` — USB-C connection, not Smart Port |
| `when autonomous` on IQ/EXP/CTE/AIM/etc. | Competition template exists only on V5 (V5RC/VURC/VAIRC). IQ has no auton/driver-control match phases. |
| `time.sleep()` anywhere | Use `wait(time, MSEC/SECONDS)` on all platforms |
| `threading.Thread()` anywhere | Use VEX `Thread(fn)` on all platforms |

---

## AI Vision / AprilTag Capability

| Platform | Color signatures | AprilTag | AI classification |
|---|---|---|---|
| IQ (1st gen) | ✅ (Vision Sensor only) | ❌ | ❌ |
| AIM | ✅ | ✅ | ✅ |
| IQ (2nd gen) | ✅ | ✅ | ✅ |
| EXP | ✅ | ✅ | ✅ |
| V5 | ✅ (AI Vision + legacy Vision) | ✅ | ✅ |
| AIR | ❌ | ✅ (both cameras) | ❌ |
| GO, 123, CTE, VR | ❌ | ❌ | ❌ |

---

## How to Use This File

1. Identify platform and language from the user's question or code context.
2. If platform is unclear, **ask before generating code** — do not assume V5 or any other default.
3. Fetch the platform llms.txt from the table above.
4. Apply universal rules above regardless of platform.
5. For cross-platform questions, check the mistakes table and comparison tables here before fetching platform files.

**Legacy IDE — VEX Coding Studio (VCS):** VCS was the predecessor to VEXcode and is no longer supported. If a user references VCS or pastes VCS-style code, note that VCS is deprecated and that VEXcode is the current IDE. VCS code is structurally similar to VEXcode C++ but may use different class names or patterns — do not treat it as equivalent.