VEXcode V5 Guide

CONTENTSWhat this guide covers

PART 1Starting a new project

1. Open VEXcode V5 (the standalone IDE — Blocks + Text app, not VS Code)
2. File → New Text Project → C++
3. When asked for a template, pick Empty Project (or "Plain C++")
4. File → Save As, give it a name like Clawbot-2822
5. The IDE creates main.cpp, vex.h, and (depending on template) robot-config.h/cpp

PART 2Configuring hardware — two paths

VEXcode V5 has two ways to tell the brain about your motors and sensors. Pick one and stick with it — mixing them causes redefinition errors.

Path A — Devices wizard step-by-step

The Devices button is in the top of the left sidebar. Click it to open the Devices panel. To add any device, click Add a Device, pick the device type, configure it, and click Done.

Add devices in this order for cleanest results:

1. Controller — always first, gates everything else
2. Drivetrain — if your robot has one (do this before adding individual motors so the wizard knows which ports are taken)
3. Individual smart motors — arm, claw, intake, anything not in the Drivetrain
4. Smart-port sensors — Distance, Optical, Vision / AI Vision
5. 3-wire devices — Limit switches, potentiometers, bumpers

1. Adding a Controller

1. Click Add a Device → Controller
2. Click Done (no other options to set)

Auto-generated code: controller Controller1 = controller(primary);

2. Adding an individual Smart Motor (arm, claw, intake)

1. Click Add a Device → Motor
2. Select the port (1-21). Ports already used by other devices appear grayed out.
3. Rename the motor (default is Motor1, Motor2, etc.). Use meaningful names like Arm, Claw, Intake.
4. Pick the cartridge: Red (100 RPM) / Green (200 RPM) / Blue (600 RPM). Must match what's physically in the motor.
5. Check Reversed if the motor spins the wrong direction (test in driver control; flip if backwards).
6. Click Done

Auto-generated code: motor Arm = motor(PORT8, ratio36_1, false);

3. Adding a Drivetrain (2-motor or 4-motor)

Only one Drivetrain per project. Picks up ports for both motors plus the IMU in one step.

1. Click Add a Device → Drivetrain 2-Motor or Drivetrain 4-Motor
2. Select the ports for the Left motors (e.g., port 1 for 2-motor; ports 1 and 2 for 4-motor)
3. Select the ports for the Right motors (e.g., port 10; or 9 and 10)
4. (Recommended) Click Inertial Sensor and select its port (e.g., 11). Required for IMU-corrected PID autons.
5. Set Wheel Size (e.g., 4" for Clawbot), Gear Ratio (usually 1:1), and Gear Cartridge (must match physical motors)
6. Click Done

Auto-generated code:

motor LeftDriveSmart  = motor(PORT1,  ratio18_1, false);
motor RightDriveSmart = motor(PORT10, ratio18_1, true);
inertial DrivetrainInertial = inertial(PORT11);
smartdrive Drivetrain = smartdrive(LeftDriveSmart, RightDriveSmart, 
                                    DrivetrainInertial, 319.19, 295, 40, mm, 1);

4. Adding 3-wire devices (limit switch, potentiometer, bumper, gyro)

3-wire devices plug into the brain's ADI ports (labeled A-H). Same workflow regardless of device type.

1. Click Add a Device → 3-Wire Devices
2. Pick the specific device: Limit Switch, Bumper Switch, Potentiometer, Encoder, Line Tracker, etc.
3. Select the 3-wire port (A-H). Ports already in use are grayed out.
4. Rename to something meaningful: ArmTop, ArmBot, ArmPot, FrontBumper, etc.
5. Click Done

Auto-generated code:

limit ArmTop = limit(Brain.ThreeWirePort.A);
limit ArmBot = limit(Brain.ThreeWirePort.B);
pot   ArmPot = pot(Brain.ThreeWirePort.C);
bumper FrontBumper = bumper(Brain.ThreeWirePort.D);

5. Adding smart-port sensors (Distance, Optical, Vision)

Smart-port sensors are simpler than 3-wire — just port assignment.

1. Click Add a Device → pick from Distance, Optical, GPS, etc.
2. Select the smart port (1-21). Avoid ports used by the Drivetrain or individual motors.
3. Rename to something meaningful: BackDist, ClawOptical
4. Click Done

Auto-generated code: distance BackDist = distance(PORT5); · optical ClawOptical = optical(PORT4);

6. Adding a V5 Vision Sensor (older) or AI Vision Sensor (new)

Vision sensors require an extra calibration step beyond just picking a port — you train them to recognize colors (and, for AI Vision, AprilTags and AI classifications).

1. Click Add a Device → Vision Sensor or AI Vision Sensor
2. Select the smart port
3. (AI Vision only) Connect via USB-C to the computer when prompted
4. The configuration window opens with the live camera feed
5. Drag a box over a colored object to teach the sensor a Color Signature
6. (Optional) Add 2+ signatures to create Color Codes (sequences of colors)
7. (AI Vision only) Toggle AprilTag detection or AI Classifications on/off — no per-tag setup needed, the sensor detects all standard AprilTags
8. Click Done

Auto-generated code (AI Vision with AprilTags enabled):

aivision AIVision1 = aivision(PORT7, aivision::ALL_AIOBJS,
                              aivision::ALL_TAGS);

See the Vision Sensor + AprilTags page for project ideas and integration patterns once vision is configured.

Editing or deleting devices

After a device is added:

• Edit: Click the device in the Devices panel → change port, rename, flip reversed, click Done
• Delete: Click the device → Delete button at the bottom. Warning: if your code references the device by name, you'll get build errors after deletion. Update or remove the references first.

Official VEX references (step-by-step with screenshots)

VEX publishes detailed walkthroughs with screenshots for each device type. Use those when you need the visual reference; come back here for what the wizard produces (the auto-generated names your code uses).

• Configuring V5 Smart Motors in VEXcode V5 ↗
• Configuring 3-Wire Devices in VEXcode V5 ↗
• Configuring a 4-Motor Drivetrain in VEXcode V5 ↗
• Configuring the V5 Controller in VEXcode V5 ↗
• Adding the V5 Vision Sensor as a Device in VEXcode V5 ↗
• Getting Started with the AI Vision Sensor ↗

Path B — manual declaration in code

Skip the Devices panel entirely. Put all hardware in Section 1 of your main.cpp:

controller Controller1 = controller(primary);

motor LeftDriveSmart  = motor(PORT1,  ratio18_1, false);
motor RightDriveSmart = motor(PORT10, ratio18_1, true);
inertial DrivetrainInertial = inertial(PORT11);

smartdrive Drivetrain = smartdrive(
    LeftDriveSmart, RightDriveSmart, DrivetrainInertial,
    319.19, 320, 40, mm, 1.0);

motor Arm  = motor(PORT8, ratio36_1, false);
motor Claw = motor(PORT3, ratio36_1, false);

limit ArmTop = limit(Brain.ThreeWirePort.A);
limit ArmBot = limit(Brain.ThreeWirePort.B);
pot   ArmPot = pot(Brain.ThreeWirePort.C);

competition Competition;

Motor cartridges — the right value matters

PART 3Understanding the code — the 9-section architecture

The reference projects organize main.cpp into 9 banner-commented sections. Each section has one job. To find any section, use Ctrl+F and search for SECTION N.

The two-API pattern (every subsystem)

Every subsystem section exposes two parallel APIs — one for opcontrol, one for autons:

PART 4Building, downloading, running

1. Click Build (hammer icon at top, or Ctrl+F5 / Cmd+B). Output panel shows progress.
2. Read errors top-to-bottom. The FIRST error is almost always the real problem — later errors are often cascading consequences. Fix #1, rebuild, re-read.
3. Connect V5 brain via USB cable. Brain icon at top of VEXcode turns green when connected.
4. Pick a slot from the dropdown if you don't want slot 1 (default).
5. Click Download (arrow icon). Watch the progress bar — takes ~5 seconds.
6. Press Run on the brain (or controller). The auton selector should appear on the brain screen.
7. Use UP/DOWN on the controller to cycle autons, A to confirm. Dashboard appears after selection.

PART 5Calibration workflow

Calibration is a one-time-per-robot process. Do it in this order — each step assumes the previous one is correct.

PART 6Common errors — lessons learned the hard way

These are the 6 errors that real teams hit when first using VEXcode V5 with our architecture. Knowing them in advance saves hours of practice time.

PART 7Using the dashboard for debugging

The sensor-loaded reference projects include a background dashboard task that prints live sensor values to the brain screen during opcontrol and auton. This is your primary debugging tool.

Sample dashboard output:

IMU heading:    142.3 deg
Arm pot angle:  87.0 deg
Arm top limit:    -
Arm bot limit:    -
Front bumper:     -
Back dist:       780 mm
Claw object:   DETECTED
Optical hue:   165.0 deg
Battery:         82 %

Use it for:

• Calibrating pot presets — move arm by hand, read live pot angle
• Verifying sensors are wired correctly — press limit switches by hand, watch "PRESSED" flash
• Diagnosing auton failures — watch IMU heading drift during a turn
• Battery monitoring — below 70% your PID drive distances start drifting
• Optical color tuning — hold objects in front of the claw, note the hue degrees

PART 8Where to go next

Adding a new subsystem (the 6-step pattern)

When your robot has a new mechanism (intake, lift, flywheel, etc.):

1. Add the motor to Section 1 HARDWARE
2. Add the new function names to Section 2 FORWARD DECLS
3. Add a new subsystem section (copy an existing one, change the names) — constants at top, then init / control / auton API
4. Call <name>_init() in Section 9 pre_auton()
5. Call <name>_control() in Section 9 usercontrol()
6. Optionally use the auton API from autons in Section 7

Adding a new auton

In Section 7:

1. Write the new auton as void auton_my_routine() { ... } using pid_drive, pid_turn, and subsystem auton APIs
2. In Section 8, add an entry to the autons[] array: {"6. My Routine", auton_my_routine}
3. Rebuild + download. The new auton appears in the selector.

Migrating to multi-file (when you outgrow single-file)

Once your main.cpp exceeds ~800 lines, consider splitting to multi-file. VEXcode V5 standalone doesn't support multi-file well — you'll need the VEX VS Code Extension (NOT the same as PROS + VS Code; much simpler). Each SECTION becomes its own .cpp + .h file. See the Setup Guide's appendix.

Migrating to PROS + EZ-Template (for competitive autons)

When you need tunable PID (custom kP, kI, kD per auton segment), exit conditions, or odometry, the path is PROS + EZ-Template. VEXcode V5's built-in PID uses VEX-tuned constants you can't change — fine for student-level autons, but tournament-winning autons usually need finer control. The architecture pattern is identical; each section maps to its own file.

Companion resources

• Setup Guide: spartandesignrobotics.org/vexcode-setup (import existing reference projects)
• Architecture Reference: spartandesignrobotics.org/code-architecture-vexcode (full pattern explanation)
• Reference projects: Clawbot, Flex, Skimmer (single-file + multi-file editions)
• PROS + EZ-Template archive: spartandesignrobotics.org/code-architecture (shelved but preserved)

PART 9Blocks vs Text — when to use which

VEXcode V5 lets students write in Blocks, Python, or C++. All three use the same Devices wizard, same competition template, and same underlying API. But each has different capabilities — here's when to pick which.

What's the same between Blocks and Text

• Same Devices wizard (Part 2 applies to both)
• Same motor / sensor / drivetrain commands — driveFor, turnFor, spin, spinToPosition
• Same competition template hat blocks: When Started → pre_auton, When Autonomous → autonomous, When Driver Control → usercontrol
• Same built-in PID via smartdrive (in Blocks, the Drivetrain "Drive for" block uses the same closed-loop control)
• Multiple When Started hat blocks run in parallel — like background tasks in text
• Custom blocks via the My Blocks category support parameters (number / boolean / label) — equivalent to text functions with arguments

What Blocks CAN'T do (where the Spartan architecture lives)

When to use Blocks

• New students with no prior programming — especially if they haven't done Scratch or similar
• Quick prototyping — testing a sensor or motor behavior before committing to a design
• Drag-and-drop visual learners — the visual flow of blocks makes parallel "When Started" stacks especially clear
• Simple competition autons — tournament-grade if the auton doesn't need subsystem encapsulation
• The first week of curriculum — Sensor Exercise 0 + Drive Test work fine in Blocks

When to use Text C++

• The Spartan 9-section architecture — the pattern is fundamentally text-based
• Competition autons with sensor fusion — Auton 5 (Sensor Mission) needs proper state management
• Multi-subsystem robots — once you have arm + claw + lift + intake, encapsulation matters
• Built-in auton selector — the function-pointer pattern requires text
• Migration to PROS — tunable PID via EZ-Template requires C++
• Industry-relevant programming skill — text-based C++ is what professional embedded developers use

The graduation path — Blocks → Text

Students don't have to pick once and stick forever. VEXcode V5 makes the transition explicit:

1. Write a behavior in Blocks (e.g., "drive forward until limit switch hits")
2. Open the Code Viewer (View menu) — see the generated C++ side-by-side with your blocks
3. Note the syntax patterns: Drivetrain.drive(forward), while (!LimitA.pressing()), wait(20, msec)
4. Create a new Text C++ project and replicate the behavior by typing the patterns
5. Extend with text-only features: function pointers, static state, structs, multi-file

The Code Viewer is a read-only learning tool — you can't edit the generated C++. Treat it as a Rosetta Stone between the two languages.

Recommendation for coaches

The Spartan curriculum (reference projects, training exercises, sensor-loaded edition) is text-based by design. Starting in Blocks for the first practice session is fine — but the moment a student wants multiple autons with a selector or soft-limit sensors gating motor commands, the natural next step is text.

PART 10The toolchain progression — Blocks → VEXcode V5 → VS Code

The Spartan curriculum moves students through three programming environments. The progression isn't arbitrary — each step changes exactly one variable at a time. You never have to learn a new language AND new tooling simultaneously.

The single-variable-change rule

What each transition unlocks

Stage 1 → Stage 2: the language transition

The student already knows the Devices wizard, the competition template, and the API. The Code Viewer in Blocks shows the C++ equivalent of every block, so the syntax isn't foreign — it's just a different way to write things they already understand.

What gets unlocked: Function pointers (auton selector), static file-scope state (subsystem encapsulation), const calibration values, printf formatting (dashboard), structs. The Spartan 9-section architecture lives here.

Stage 2 → Stage 3: the tooling transition

The student already knows VEX C++, the SDK, the build/download workflow. Now they keep all of that but get a professional editor.

What gets unlocked: Multi-file projects (separate .cpp files per subsystem), IntelliSense (autocomplete + hover docs), Git integration, AI Copilot, the same tools 75% of professional developers actually use. According to VEX, this transition exists specifically to align with industry tooling.

Why not skip Stage 2 — Blocks straight to VS Code?

Why VEX themselves designed it this way

VEX retired their old VEXcode Pro V5 (their proprietary text-only IDE) in favor of the VS Code Extension. The thinking is two-fold:

• VEXcode V5 stays simple as the on-ramp — Blocks + Text in one app, no install complexity, runs on Chromebooks
• VS Code Extension is the professional landing zone — multi-file, Git, IntelliSense, AI tooling. The same VS Code that millions of professional developers use, with VEX support layered on top

VEXcode Pro V5 was the awkward middle ground that didn't serve either purpose well, so VEX killed it. The Blocks → VEXcode V5 Text → VS Code Extension progression is now the official VEX-recommended path.

What each step costs to gain

When each student moves up

• Blocks → Text: when they want a real auton selector, soft-limit sensors that gate motor commands, or a dashboard with formatted sensor data
• Text → VS Code: when one main.cpp becomes unwieldy (typically multi-subsystem robots with arm + lift + claw + intake all in one file), or when they want to use Git for version control across multiple programmers

What this looks like in practice for our team