🔒 SPARTAN 2822 — INTERNAL TEAM RESOURCE
Class-by-class quick reference for the VEXcode V5 classes the team's reference projects (Clawbot-First-Class, Flex-First-Class, Skimmer-First-Class, Kite-First-Class) use. Mirrors the "Sensor API quick reference" table from clawbot-first-class/README.md and flex-first-class/README.md but expanded class-by-class. Not for public distribution.
// Section 01
VEXcode V5 API — Quick Reference 📝
When to use this page: during code reviews, during Phase C summer camp when students ask "how do I get the IMU heading?", and when porting EZ Template patterns to VEXcode V5. Each class has a kv-table of the methods the team actually uses. Methods not in the team's curriculum are intentionally omitted — the official VEX API docs at api.vex.com ↗ are the comprehensive source.
How to read this page
Each row in a class table is: label on the left, full method signature plus a one-line description on the right. Where useful, the description includes parameter ranges or common gotchas. Code that actually compiles is in monospace.
The VEX C++ Namespace
All VEXcode V5 classes live in the vex namespace. The Devices Wizard generates vex::motor Arm(...), vex::inertial Inertial(...), etc. as global instances. The using namespace vex; line at the top of main.cpp (generated by the wizard) lets us write motor instead of vex::motor in the rest of the file.
Class Index — What Each Tab Covers
Brain + Controller
vex::brain, vex::controller — the two classes every project uses. Brain screen, battery, timers; controller axes, buttons, rumble.
Motors + Drive
vex::motor, vex::motor_group, vex::smartdrive — everything that turns a wheel. Position presets, velocity commands, the Drivetrain wizard methods.
IMU + Rotation
vex::inertial, vex::rotation — heading, rotation, calibration. Plus the rotation sensor for arm angle and lift positions.
Optical + Distance + Bumper
vex::optical, vex::distance, vex::bumper — the perception sensors. Plus the 3-wire ADI bumper switch construct.
AI Vision
vex::aivision — AprilTags, color signatures, AI classifications. The big one for autonomous routing.
Team Helpers
Team 2822 helper functions defined in the first-class reference projects: arm_pot_angle(), claw_grab_smart(), wall_align(), etc.
The Devices Wizard — Where Hardware Objects Come From
Path A means hardware lives in VEXcode V5's Devices wizard (the left sidebar of the IDE). Adding a device there generates a global instance with the name you gave it. The team's reference projects use these standardized names:
Brain
Always present as Brain. No wizard config needed.
Controller1
The primary controller. Always present as Controller1.
Arm, Claw, Lift, Intake, etc.
Motors named after the mechanism they drive. Wizard generates vex::motor Arm(PORT1, ratio18_1, false); for the Clawbot's arm.
Drivetrain
Smart Drivetrain (motor group + inertial sensor combined). Wizard generates a vex::smartdrive Drivetrain(...); with all the kinematics math built in.
Inertial, DrivetrainInertial
IMU sensor. Often two on the team's bots: one for the chassis (used by Drivetrain), one for standalone heading reads.
ArmRotation, LiftRotation
Rotation sensor on the arm pivot or lift drive.
ClawOptical, IntakeOptical
Optical sensor inside a mechanism for object detection.
BackDistance, FrontDistance
Distance sensor mounted to read wall distance.
FrontBumper, ArmTop, ArmBottom
3-wire bumper switches for wall contact and endpoint limits.
Vision1
V5 Vision Sensor (color signatures only). The OLD vision sensor.
AIVision1
AI Vision Sensor (color sigs + AprilTags + AI classifications). The NEW vision sensor.
Cross-Reference to Team Pages
Clawbot training
/clawbot-training — the curriculum that builds up to using these classes
vex::gps (GPS Sensor) is intentionally omitted from this reference because no first-class project uses it for Override 2026-27. Per kite-first-class/main.cpp lines 117–123: “GPS subsystem is DISABLED for V5RC Override. Override's field has 9 element plates (vs Push Back's 4), vertical Pin/Cup stacks, and dense midfield endgame — line-of-sight to the perimeter GPS strip is occluded too often for GPS to be a reliable primary sensor.”
The team uses AprilTags via AI Vision for absolute-pose correction instead (see Section 6 above) — tags are spread across goal faces throughout the field, not concentrated on a single perimeter strip, so they don't have the occlusion problem. The Kite project keeps a dormant GPS stub (commented device line + GPS_QUALITY_THRESHOLD constants + an empty correction block in odom_task()) so it can be re-enabled for future seasons or skills runs where line-of-sight is clearer. If a team enables that stub, the relevant API is documented in the /sensors-gps page on the private site.
// Section 02
Brain + Controller 🎮
The two classes every project uses. Brain handles the LCD screen, battery, timers, and SD card. Controller handles driver input (sticks + buttons) and haptic output.
vex::brain
Global instance Brain — always present, no wizard config.
Screen (LCD)
Print at cursor
Brain.Screen.print("Hello %d", 42); — printf-style, prints at current cursor position
Set cursor (1-indexed)
Brain.Screen.setCursor(row, col); — row 1–12, col 1–40 (approx)
New line
Brain.Screen.newLine(); — advance cursor to next row
Print at pixel coords
Brain.Screen.printAt(x, y, "text"); — (x, y) in pixels, top-left origin
Clear screen
Brain.Screen.clearScreen();
Clear line
Brain.Screen.clearLine(row);
Set fill color
Brain.Screen.setFillColor(color::red); — for drawn shapes
Set pen color
Brain.Screen.setPenColor(color::white); — for text and lines
Brain.Timer.system(); — ms since brain boot, monotonic
Time since reset
Brain.Timer.value(); — seconds (double) since last reset
Reset timer
Brain.Timer.reset(); — zero the timer
Time elapsed
Brain.Timer.time(msec); — alternative to .value(), explicit units
SD Card
Is inserted
Brain.SDcard.isInserted(); — bool
Read file
Brain.SDcard.loadfile("name.txt", buffer, size);
Write file
Brain.SDcard.savefile("name.txt", buffer, size);
vex::controller
Global instance Controller1 — the primary controller. Add Controller2 via the wizard for a partner controller.
Sticks (Analog Axes)
Axis numbering matches the controller silkscreen: Axis 1/2 are the right stick, Axis 3/4 are the left stick. All return -100 to +100 as percent.
Right stick X (turn, often)
Controller1.Axis1.position(percent);
Right stick Y
Controller1.Axis2.position(percent);
Left stick Y (drive forward)
Controller1.Axis3.position(percent);
Left stick X
Controller1.Axis4.position(percent);
Stick value (alt)
Controller1.Axis3.value(); — raw integer, -127 to +127
Buttons (Digital)
All buttons expose .pressing() returning a bool. For one-shot macros, save the last-frame value and detect rising edges manually (the team's pattern; see Section 7 of clawbot-training).
Controller1.rumble("."); — short pulse. Use "-" for long, "." for short, spaces for gaps. Examples: ".." = double short, "-." = long-short, ". -." = short, gap, long-short
Controller Screen
Small LCD on the controller itself — useful for driver status without looking at the brain.
Print on controller
Controller1.Screen.print("Mode: SLOW");
Set cursor
Controller1.Screen.setCursor(row, col); — row 1–3, col 1–19
Clear line
Controller1.Screen.clearLine(row);
Clear screen
Controller1.Screen.clearScreen();
// Section 03
Motors + Drivetrain ⚙️
Everything that turns a wheel. vex::motor for individual mechanisms (arm, claw, intake). vex::motor_group when several motors move together. vex::smartdrive for the drivetrain with IMU integration.
vex::motor
Generated by the Devices Wizard for each named motor.
Constructor (wizard-generated)
Signature
motor Arm(PORT1, ratio18_1, false); — (port, gear cartridge, reversed)
Arm.setVelocity(80, percent); — applied to spin() and spinFor() when velocity not specified
Set stopping mode
Arm.setStopping(hold); — default mode for stop(). The team uses hold for arm so it holds position without driver input.
Set max torque
Arm.setMaxTorque(50, percent); — limits how hard the motor will push
Zero the encoder
Arm.setPosition(0, degrees); — declares "this is now position 0"
Reverse direction
Arm.setReversed(true); — flips all subsequent commands
Reading State
Current position
Arm.position(degrees); — encoder reading since boot or last setPosition()
Current velocity
Arm.velocity(rpm); or Arm.velocity(percent);
Current torque
Arm.torque(torqueUnits::Nm); — useful for stall detection
Motor temperature
Arm.temperature(temperatureUnits::celsius); — check during matches; motors throttle >55°C
Current draw
Arm.current(amp);
Is moving
Arm.isSpinning(); — bool
Is done
Arm.isDone(); — bool, true once a spinFor/spinToPosition completes
vex::motor_group
Wraps multiple motors as a single unit — useful when a mechanism has 2+ motors that always move together (e.g., a dual-motor lift).
Construction
From individual motors
motor_group Lift(LiftLeft, LiftRight); — both motors share commands and report aggregate state
Methods are identical to vex::motor — spin(), spinFor(), spinToPosition(), setVelocity(), setStopping(), position(), velocity(), isDone(), etc. Commands fan out to all motors in the group; reads return the average (or first motor, depending on method). For independent motor control, instance each motor separately and skip the group.
vex::smartdrive (Drivetrain)
The drivetrain class created by the Devices Wizard "Drivetrain" option. Combines a motor_group (or two for tank-style) with an Inertial sensor for kinematics math.
Driving
Drive continuously
Drivetrain.drive(forward, 50, percent); — (direction, velocity, units). Use reverse for backward.
Drivetrain.isDone(); — bool, last blocking command finished
// Section 04
Inertial (IMU) + Rotation 🧮
Two distinct sensors that both measure rotational state. The IMU tracks robot orientation in space (yaw / pitch / roll). The Rotation sensor measures angular position of a single shaft (arm pivot, lift drive, dead-wheel odometry).
vex::inertial
Global instance via wizard, typically Inertial or DrivetrainInertial.
Calibration (critical)
⚠️
The IMU must calibrate at boot, with the robot perfectly still, for about 2 seconds. Calibration must complete before any heading reads. The wizard inserts Inertial.calibrate(); while(Inertial.isCalibrating()) wait(50, msec); at the start of pre_auton() for this reason. If the bot moves during calibration, headings drift — recalibrate before each match.
Start calibration
Inertial.calibrate(); — non-blocking; bot MUST be still
Is calibrating
Inertial.isCalibrating(); — bool; wait on this
Heading and Rotation
Heading (yaw)
Inertial.heading(degrees); — 0–360, wraps at boundary
Rotation (unbounded yaw)
Inertial.rotation(degrees); — can be -1440 or +1440 or anything; counts full revolutions
Set heading
Inertial.setHeading(0, degrees); — declare current orientation as the 0° reference
Set rotation
Inertial.setRotation(0, degrees); — zero the unbounded counter
ArmRotation.angle(degrees); — 0–360, wraps. Useful for absolute mechanism position.
Accumulated position
ArmRotation.position(degrees); — unbounded; counts full revolutions. Useful for lifts and intakes.
Current velocity
ArmRotation.velocity(rpm);
Configuration
Reset position
ArmRotation.resetPosition(); — sets position() to 0; angle() unaffected
Set position
ArmRotation.setPosition(0, degrees); — declare a new zero for position()
Reverse direction
ArmRotation.setReversed(true);
// Section 05
Optical + Distance + Bumper 👀
The three perception sensors most often used inside mechanisms. Optical for color and proximity, Distance for wall and object distance, Bumper for contact detection.
vex::optical
Color + brightness + proximity sensor with white LED. Sits inside mechanisms (claw, intake) to detect picked-up game elements.
Construction
Wizard-generated
optical ClawOptical(PORT6);
Color and Brightness
Hue (0–360)
ClawOptical.hue(); — returns 0–360 degrees on the color wheel; double type
Brightness (percent)
ClawOptical.brightness(); — 0–100, ambient light
Saturation
ClawOptical.saturation(); — 0–1.0; low saturation means white/gray
Surface dependency: Distance sensor reads vary by wall surface and color. Drywall, carpet, concrete, and gym tile all reflect differently. Always recalibrate the trigger thresholds when the bot moves environments (this is the Phase D async take-home calibration drift the team logs in notebooks).
vex::bumper (3-wire)
Spring-loaded plunger contact switch. Connects via the 3-wire ADI ports on the Brain (A–H), not a Smart Port. Best for repeated wall contact (e.g., front bumper for auton wall-zero).
Construction
Wizard-generated
bumper FrontBumper(Brain.ThreeWirePort.A); — (3-wire port reference)
Reading
Is pressed
FrontBumper.pressing(); — bool, true while pressed
Press count
FrontBumper.pressedCount(); — total presses since boot (rising-edge count)
⚠️
Bumper vs Limit Switch: The 3-wire bumper switch (VEX 276-4858 v2) has a plunger built for repeated wall contact. The 3-wire limit switch has a thin lever for light mechanism endpoint contact. Both behave identically in code, but only the bumper survives match-day wall slams. VEX KB: Bumper vs Limit ↗
// Section 06
AI Vision (AprilTags + Color Sigs) 📷
The AI Vision Sensor (different from the older V5 Vision Sensor). Detects AprilTags, configured color signatures, color codes, and pre-trained AI Classifications. For AprilTags, must be enabled in the AI Vision Utility USB app first.
📚
Before using: AprilTag detection mode must be toggled on once via the AI Vision Utility (open from VEXcode V5 Devices menu, plug in via USB, toggle AprilTags ON, save). Settings persist on the sensor. See /sensors-apriltags for the full setup walkthrough and the official VEX KB article ↗.
vex::aivision
Global instance AIVision1 via wizard. (The OLD V5 Vision Sensor uses vex::vision — same patterns, but no AprilTag support.)
Construction
With AprilTags only
aivision AIVision1(PORT8, aivision::ALL_TAGS);
With color signatures
aivision AIVision1(PORT8, RED_GOAL_SIG, BLUE_GOAL_SIG); — up to 7 signatures
AIVision1.objectCount; — number of detections from last snapshot
Per-Object Fields (after snapshot)
Access via AIVision1.objects[i], 0-indexed, where i < objectCount.
Tag ID
AIVision1.objects[i].id; — for AprilTags, the tag number (0–37 for the VEX 38-tag set)
Center X (pixels)
AIVision1.objects[i].centerX; — horizontal pixel position; image center is ~160
Center Y (pixels)
AIVision1.objects[i].centerY; — vertical pixel position; image center is ~120
Width (pixels)
AIVision1.objects[i].width; — bounding box width; inversely proportional to distance
Height (pixels)
AIVision1.objects[i].height;
Angle (AprilTags only)
AIVision1.objects[i].angle; — rotational angle of tag relative to sensor, 0–359
Score (AI classifications)
AIVision1.objects[i].score; — confidence 0–100; AI classifications only
Common Pattern — Look for a Specific Tag
int find_tag(int target_id) {
AIVision1.takeSnapshot(aivision::ALL_TAGS);
for (int i = 0; i < AIVision1.objectCount; i++) {
if (AIVision1.objects[i].id == target_id) {
return i; // found at index i
}
}
return -1; // not found
}
Common Pattern — Drive Toward a Tag
// Centers the bot on tag ID 4 (alliance goal).
// Assumes image center is 160 pixels in X.
while (true) {
AIVision1.takeSnapshot(aivision::ALL_TAGS);
int idx = find_tag(4);
if (idx == -1) { Drivetrain.stop(); break; } // lost the tag
int dx = AIVision1.objects[idx].centerX - 160;
if (abs(dx) < 10) { Drivetrain.stop(); break; } // centered
Drivetrain.arcade(40, dx / 3); // P-controller on bearing
vex::wait(20, msec);
}
/vision-sensor — project ideas + official VEX KB references
Reference projects
The kite-first-class and skimmer-first-class projects have working AprilTag-aware autons with KNOWN_TAGS[] position tables.
// Section 07
Team Helper Functions 🤝
Functions defined in the team's first-class reference projects (clawbot-first-class/main.cpp, flex-first-class/main.cpp). These wrap VEX library calls into team-canonical operations — same name across all robots so code reads consistently.
📍
These helpers live in main.cpp at file scope. Copy them into a new project from the reference project, or write your own equivalents from scratch using the underlying VEX class methods documented in Sections 2–5 above. The README's "Sensor API quick reference" table in the first-class projects is the canonical short-form of this section.
Arm Subsystem
arm_init()
void arm_init(); — configures the arm motor (stopping mode = hold, default velocity, reset position). Call once at boot.
arm_control()
void arm_control(); — reads R1/R2 buttons and applies powered arm control with soft limits. Call every cycle inside usercontrol().
arm_set_power(p)
void arm_set_power(int power); — (-100 to +100); applies via get_safe_arm_power() if soft limits are enabled.
arm_stop()
void arm_stop(); — thin wrapper for Arm.stop();
arm_pot_angle()
double arm_pot_angle(); — returns 0–250° from the arm rotation sensor. Wrapper for ArmRotation.angle(degrees);
arm_to_pot_angle(target, timeout)
void arm_to_pot_angle(double target_deg, int timeout_ms = 3000); — drives arm to absolute angle, with timeout safety. Blocking.
Claw Subsystem
claw_init()
void claw_init(); — configures claw motor (hold stopping, default velocity). Call once at boot.
claw_control()
void claw_control(); — reads L1/L2 buttons and handles open/close. Call every cycle inside usercontrol().
claw_open_set()
void claw_open_set(); — drives claw to the open position (non-blocking).
claw_close_set()
void claw_close_set(); — drives claw to the closed position (non-blocking).
claw_is_open()
bool claw_is_open(); — true if last commanded state was open.
claw_has_object()
bool claw_has_object(); — optical-gated; true if ClawOptical.objectDetected().
claw_grab_smart(timeout)
void claw_grab_smart(int timeout_ms = 1500); — closes claw and waits until optical confirms an object or timeout fires. Blocking.
Distance / Bumper Helpers
back_distance_mm()
double back_distance_mm(); — wrapper for BackDistance.objectDistance(mm);
front_bumper_pressed()
bool front_bumper_pressed(); — wrapper for FrontBumper.pressing();
wall_align(target_mm, max_inches, vel_pct)
void wall_align(int target_mm = 100, int max_inches = 36, int velocity_pct = 30); — drives backward until back-distance sensor reads target_mm; max_inches is the timeout safety distance. Used for auton zeroing.
Auton Library (first-class projects)
auton_drive_test()
void auton_drive_test(); — the Section 6 baseline auton (forward / turn / stop / claw close)
auton_square_drill()
void auton_square_drill(); — drives a square (4 sides + 4 turns); IMU calibration test
auton_arm_cycle()
void auton_arm_cycle(); — raises arm through all three positions; rotation sensor test
auton_grab_and_score()
void auton_grab_and_score(); — pickup + drive + score; integration test
int dashboard_task(); — the background brain-screen dashboard. Start with vex::thread dt(dashboard_task);
render_selector()
void render_selector(); — draws the brain-screen auton selector
run_selector()
void run_selector(); — entry point that waits for the user to pick an auton and dispatches
Source — where these are defined
Header declarations are at lines 133–164 of reference-projects/clawbot-first-class/main.cpp (and the matching lines in flex-first-class/main.cpp). The full implementations follow at lines 186 onward. Copy them as a starting point for new projects, then customize for the actual mechanism geometry.
Cross-references
Sensor API quick reference
The first-class README's table (8 entries) is the short-form summary. This page is the expanded version.
Clawbot training
/clawbot-training — Sections 5 (Sensors) and 7 (Macros) build up to the patterns the helpers wrap.
This site is an informational reference. RECF EN4 prohibits AI-generated content in engineering notebooks and programming code. Rewrite everything in your own words.