01 | WHY A COMPETITION PROJECT NEEDS STRUCTURE

A match has different operating modes. In autonomous, the robot follows programmed actions. In driver control, it responds to live input. Field controls enable and disable the robot and select the mode.

Putting everything in one unstructured loop makes it difficult to separate those jobs. A competition project gives each mode a named function and registers it with the VEX Competition class.

This guide focuses on structure. The example displays status messages and stops the drive motors; it contains no motor movement commands.

02 | GENERATED CONFIGURATION IS NOT THE COMPETITION LOGIC

A new text project contains a VEXcode Generated Robot Configuration region. That region defines configured devices and supporting setup. It is different from your autonomous and driver-control functions.

Keep your team code below # Begin project code. Do not insert your own instructions inside the generated region, where VEXcode can overwrite them.

Use File → Open Examples to find the Competition Template, choosing Python for this course. You can also structure a Python text project with the Competition class as shown below. Do not combine two complete templates and leave duplicate callback registration or startup loops.

03 | THREE JOBS TO KEEP SEPARATE

The name pre_autonomous is our organisational convention. It runs because startup code calls it explicitly. It is not a third callback passed to Competition.

In this example it runs once each time the project starts, not automatically before every later autonomous enable. Plan any between-run reset deliberately.

04 | SETUP MUST FINISH

Preparation might later include inertial calibration, resetting encoder references or selecting an autonomous routine. Calibration should take place while the robot is still and before the match is enabled.

Keep setup finite. An endless while True loop inside pre_autonomous would prevent this example from reaching callback registration. Setup code should not drive the robot around while it waits for a match.

Readiness is a condition you verify, not a message alone. In this guide, Setup ready confirms only that the simple startup function reached its end.

05 | AUTONOMOUS IS AN ACTION SEQUENCE

Write autonomous as a sequence with a clear beginning and end. Shared helper functions can later express actions such as drive a distance, turn or move a mechanism.

Motor movement routines should have sensible completion conditions and timeouts. A robot that misses a target should not push indefinitely while later actions wait.

Finishing autonomous does not itself switch the match into driver control. Competition control selects the next mode. Do not call driver_control at the end of autonomous.

06 | DRIVER CONTROL REPEATS

A driver may change joystick position at any moment, so the program needs repeated input updates. The example uses a loop that runs while the robot is enabled and in driver-control mode.

while competition.is_enabled() and competition.is_driver_control():
    # Read controls and update outputs here.
    wait(20, MSEC)

The 20 ms pause provides a regular update rhythm and lets other work run. Later guides add joystick mixing and mechanisms inside this loop.

When you introduce extra threads or button callbacks, keep their actions consistent with the current mode. A competition object does not automatically organise every background task you create.

07 | REGISTER FUNCTIONS WITHOUT CALLING THEM

competition = Competition(driver_control, autonomous)

The order is driver control first, autonomous second. These are function objects that the Competition class can call when the relevant period begins.

driver_control() with parentheses executes the function now. driver_control without parentheses passes the function as a callback. Using calls inside the constructor arguments can start a loop before registration ever completes.

Both functions must be defined before this line executes. The object name competition is used by the driver loop to inspect mode and enabled state.

08 | A CLEAR FOUR-MOTOR STARTER

Keep the existing generated imports and Brain definition above the following user code. Replace earlier demonstration user code, rather than adding another main call or startup loop.

The example declares ports explicitly, using the layout from 01.3. Match these settings to your real hardware. If you use manual declarations, do not also configure those same drive motors through the Devices panel.

# =============================================================================
# TEAM [MY TEAM NAME / NUMBER]
# =============================================================================
# ROBOT CONFIGURATION
# - FOUR-motor drivetrain:
#       Left  = Ports 3 and 4
#       Right = Ports 1 and 2
# - Example: blue cartridges, left normal, right reversed.
#   VERIFY your actual ports, cartridges and direction settings.
# - This starter contains no motor movement commands.
# - Add BELOW # Begin project code, outside generated configuration.
# - Do not also define these drive motors in the Devices panel.
# - Keep generated from vex import * and brain = Brain() above.

# =============================================================================
# FOUR-MOTOR DRIVETRAIN
# =============================================================================
left_motor_1 = Motor(Ports.PORT3, GearSetting.RATIO_6_1, False)
left_motor_2 = Motor(Ports.PORT4, GearSetting.RATIO_6_1, False)
right_motor_1 = Motor(Ports.PORT1, GearSetting.RATIO_6_1, True)
right_motor_2 = Motor(Ports.PORT2, GearSetting.RATIO_6_1, True)

left_drive = MotorGroup(left_motor_1, left_motor_2)
right_drive = MotorGroup(right_motor_1, right_motor_2)

# =============================================================================
# SHARED SETTINGS AND HELPERS
# =============================================================================
LOOP_DELAY_MS = 20

def show_status(message):
    brain.screen.clear_screen()
    brain.screen.set_cursor(1, 1)
    brain.screen.print(message)

def stop_drive():
    left_drive.stop(BRAKE)
    right_drive.stop(BRAKE)

# =============================================================================
# PRE-AUTON: CALLED ONCE AT PROJECT STARTUP
# =============================================================================
def pre_autonomous():
    stop_drive()
    show_status("Setup ready")
    # Later: initialise sensors and starting values here.
    # Finish setup before the robot is enabled for a match.

# =============================================================================
# AUTONOMOUS: A FINITE ROUTINE
# =============================================================================
def autonomous():
    show_status("Autonomous")
    # Later: add your tested autonomous action sequence here.
    # This guide does not move the motors.
    stop_drive()

# =============================================================================
# DRIVER CONTROL: REPEATING UPDATES WHILE ENABLED
# =============================================================================
def driver_control():
    show_status("Driver control")
    while competition.is_enabled() and competition.is_driver_control():
        # Next guide: read joysticks and set left/right drive output.
        wait(LOOP_DELAY_MS, MSEC)
    stop_drive()

# =============================================================================
# PROGRAM START: SETUP, THEN CALLBACK REGISTRATION
# =============================================================================
pre_autonomous()
competition = Competition(driver_control, autonomous)

# Keep the main task alive without running a driving loop here.
while True:
    wait(100, MSEC)

For a two- or six-motor robot, replace only the motor declarations and groups with your verified layout from 01.3. Keep the left_drive and right_drive interface names, so the shared stop helper still works.

This starts preparation before registering callbacks. Start and finish preparation while disabled. The final waiting loop keeps the main task alive; it is not a second driver-control loop.

09 | TEST MODES, NOT JUST RUN

Downloading and pressing Run proves that the project starts. It does not by itself prove that field-controlled autonomous, driver control and disabled transitions work correctly.

Use the appropriate competition switch, field controls or supported competition-testing controls available in your setup, with your teacher. Check the screen messages as you select modes. Confirm the robot is disabled before restarting the project.

A screen message may remain after disabling; it is not a live enabled indicator. Observe the competition controls and robot state. Once movement is added, repeat the transition tests with clear space and a way to stop the robot.

10 | COMMON STRUCTURE MISTAKES

• Code vanishes after reopening: move user code out of the generated region.
• Setup never finishes: remove an endless loop or investigate a sensor wait that never completes.
• Callbacks never register: check for an earlier blocking loop or function call.
• Wrong function starts: check Competition argument order and the selected mode.
• Old test also runs: remove previous startup calls and duplicate registration.
• Robot behaviour carries across modes: inspect background threads, event handlers and persistent state, then repeat disabled-transition tests.

CHALLENGES | PROVE THE PROJECT STRUCTURE

1. Label the file: identify generated setup, manual hardware definitions, helpers, pre-auton, autonomous, driver control and startup.
2. Match the robot: replace the example ports, cartridges and reversals with your verified map.
3. Startup test: download and verify the preparation message while disabled.
4. Mode test: record the autonomous and driver-control messages using suitable competition controls.
5. Transition test: disable and re-enable each mode, noting what runs again and what does not.
6. Explain callbacks: tell a partner why callback names have no parentheses in the constructor.
7. Prepare for 01.6: mark where Controller setup and joystick updates will be added.

OFFICIAL REFERENCES

• VEX V5 Python Competition API
• VEX competition-template overview

This is an independent learning resource. VEX and VEXcode are trademarks of their respective owners.