Cookie CodersFTC Team 39092
Programs / Auto-Cal-Movement
Distance & Sensor Comparison // Student lesson

Auto-Cal-Movement

Movement Calibration

Use a controlled forward-and-back trip to calibrate and cross-check drive-motor encoder ticks, goBILDA Pinpoint odometry, and Limelight 3A observations of AprilTag clusters against a tape measurement. The goal is accurate distance reports in matching units and directions, with timestamps aligned so all three describe the same movement.

Differences can flag a lagging or stalled motor and guide checks for encoder/configuration errors or a mechanical fault. A software patch may correct settings or timing, or compensate for a measured, repeatable imbalance. It cannot repair broken gears, bearings, wiring, or a damaged motor; inspect and repair physical faults before retesting.

Four-second sensor tour: motor encoders count rotation, Pinpoint reads passive odometry wheels, and Limelight 3A observes a fixed AprilTag cluster. Each is highlighted in turn, then compared using a shared reference and timestamps. These are schematic illustrations, not a mounting or wiring guide.
Start with a question

If all three sensor systems agree about how far the robot moved, how could a tape measure still tell a different story?

By the end, you can…

  • Trace how a held bumper and fresh camera frames permit or pause motion.
  • Convert a 36-inch target and signed sensor changes into matching distance units.
  • Explain origin, endpoint, settling, and return residual using an independent tape reference.
Start learningJump to CodeQuizDownload Blocks (.blk)

Before running: Ask your supervisor first. Keep Driver Station STOP ready.

Read · predict · explain

Build the idea, one block at a time

Read these steps before exploring the full program. The numbered blue comments in the diagram link back to the matching step.

01Give four motors a shared convention

Actual Blocks for this section
Blocks for Give four motors a shared convention
Blocks to notice
  • set Direction
  • set ZeroPowerBehavior
  • set Mode
  • zeroDrive

Setup configures front-right FORWARD and the other three motors REVERSE, with BRAKE and RUN_USING_ENCODER on all four. These settings define how a shared signed power command is applied. The program starts with zero power and a WAIT phase, so preparation is separate from travel.

For example: All four motors can receive +0.10 even though their configured direction labels are not all the same. Wiring and mounting determine how those settings produce chassis motion.

Think first

Does BRAKE mean the robot cannot coast at all?

Show Answer

No. It sets zero-power behavior; actual stopping also depends on the mechanism and floor.

02Put the target in the sensor's units

Actual Blocks for this section
Blocks for Put the target in the sensor's units
Blocks to notice
  • set targetInches
  • number 36
  • multiply
  • set targetMm

The default target is 36 inches. Multiplying by 25.4 converts it to 914.4 millimeters, the unit used for the Pinpoint endpoint comparison. The target is the one-way distance, not the sum of the out and return legs.

For example: A 12-inch target would convert to 304.8 mm. With supervisor review, editing targetInches to 6, 12, 24, or 36 uses one of the helper's accepted targets.

Think first

If the default target is 914.4 mm, should the outward threshold be twice that for an out-and-back trip?

Show Answer

No—the outward leg is one target distance.

03Look at sensors while staying still

Actual Blocks for this section
Blocks for Look at sensors while staying still
Blocks to notice
  • opModeInInit
  • roundTripObserve
  • roundTripReport
  • zeroDrive

INIT updates sensor observations and displays them while repeatedly requesting zero power. This is a chance to inspect readings before START. Displaying a range reading does not make it a motion guard: the INIT ranges are display-only.

For example: A range value can change while the robot is in INIT, but that display does not add an automatic obstacle stop to this program.

Think first

What should the motor command be throughout INIT?

Show Answer

Zero, even while the sensors are producing new readings.

04Require a driver and fresh observations

Actual Blocks for this section
Blocks for Require a driver and fresh observations
Blocks to notice
  • get LeftBumper
  • roundTripValidFps
  • compare ≥ 5
  • logic AND

Motion requires LEFT BUMPER held AND at least five distinct valid cluster frames in the rolling last second. A frame is one camera observation, not one tag. Re-reading the same frame does not make it new. Releasing the bumper or losing the frame gate requests zero; travel resumes only when both gates pass again.

For example: One frame containing four tags, read four times, still counts as one frame. Valid frames A, B, C, D, and E within 0.9 seconds make five observations.

Think first

With five valid recent frames but LEFT BUMPER released, may the motors run?

Show Answer

No. Both sides of AND must be true.

05Remember one starting point

Actual Blocks for this section
Blocks for Remember one starting point
Blocks to notice
  • phase WAIT
  • roundTripCaptureOrigin
  • set phase
  • roundTripPinMm

The first time the WAIT gates pass, the program captures the origin and changes to FORWARD. The origin is a software baseline: later readings subtract the starting values rather than resetting the hardware's raw position. It is captured once for this trip, so a pause does not move the origin.

For example: If starting raw X is 1000, a later raw X of 2000 represents a change of 1000 counts—not a trip of 2000 counts. Capturing the origin changes phase; forward power begins on a later loop.

Think first

If you pause halfway out and resume, does the remaining goal become a new 36-inch trip?

Show Answer

No. The original origin and target stay in place.

06Use Pinpoint to choose the outward endpoint

Actual Blocks for this section
Blocks for Use Pinpoint to choose the outward endpoint
Blocks to notice
  • compare pinMm ≥ targetMm
  • set power
  • zeroDrive
  • roundTripMarkStop

During FORWARD, passing the bumper/frame gates requests +0.10 power. When Pinpoint X displacement reaches or exceeds targetMm, the program commands zero and enters FORWARDSETTLE. Wheels and camera provide comparisons, not the distance-stop decision.

For example: At the default target, Pinpoint reaching 914.4 mm selects the outward stop. A camera estimate of 914.4 mm by itself does not select that stop.

Think first

If the camera and Pinpoint disagree, which measurement chooses this distance endpoint?

Show Answer

Pinpoint X. The supervisor still uses STOP for unsafe motion.

07Measure after the stop has settled

Actual Blocks for this section
Blocks for Measure after the stop has settled
Blocks to notice
  • roundTripSeconds
  • add 0.8
  • compare ≥ settleUntil
  • roundTripCaptureEndpoint

The program waits 0.8 seconds after its endpoint stop command while requesting zero. The endpoint camera median uses frames after the first 0.25 seconds of that wait, reducing the influence of the initial stopping motion. A median is the middle of a sorted set of values; it is a summary, not a promise that every reading is exact.

For example: For camera values 908, 910, and 950 in the chosen measurement axis, the median is 910. Both the outward and return endpoints have a settling phase.

Think first

Does a zero command mean the final position must equal the position at the instant of the command?

Show Answer

No. Coast can change the settled position.

08Return toward the same origin

Actual Blocks for this section
Blocks for Return toward the same origin
Blocks to notice
  • phase BACKWARD
  • compare pinMm ≤ 0
  • set power
  • phase RETURNSETTLE

After the outward endpoint is captured, BACKWARD requests −0.10 when both motion gates pass. The return endpoint is selected when Pinpoint displacement is at or below zero. The robot then commands zero and settles again. A pause retains this return goal instead of creating a new origin.

For example: At +300 mm, the return has not reached the software origin. At −2 mm, the ≤ 0 comparison selects the return stop, followed by settling.

Think first

If Pinpoint is already at or below zero, does the program need another camera distance threshold to stop?

Show Answer

No. That Pinpoint comparison selects the endpoint.

09Save a completed trip for comparison

Actual Blocks for this section
Blocks for Save a completed trip for comparison
Blocks to notice
  • roundTripCaptureEndpoint
  • roundTripComplete
  • phase COMPLETE
  • roundTripReport

After the return settling wait, an active program captures the endpoint and asks to record the completed trip. Successful recording selects COMPLETE and keeps power zero. Completed measurements are written to /sdcard/FIRST/calibration_results.jsonl for comparison with your tape notes. STOP before completion is not a completed record.

For example: An outward stop is only part of the trip. The return endpoint and its settling wait must also finish before the program records completion.

Think first

If STOP occurs 0.4 seconds into the 0.8-second return settling wait, should you label that trial completed?

Show Answer

No—record it separately as stopped.

10Make zero a four-motor instruction

Actual Blocks for this section
Blocks for Make zero a four-motor instruction
Blocks to notice
  • zeroDrive
  • set Power
  • number 0

zeroDrive requests zero from each of the four drive motors. The control loop also begins its power choice at zero, leaving motion off during WAIT, pauses, settling, and finished phases unless a travel branch permits power. Zero removes the drive request; it does not remove inertia.

For example: Releasing LEFT BUMPER partway out gives all four motors a zero command while preserving the outward phase and target.

Think first

Is leaving one motor at its old +0.10 command equivalent to zeroDrive?

Show Answer

No. All four outputs need the zero request.

11End the trial, not just pause it

Actual Blocks for this section
Blocks for End the trial, not just pause it
Blocks to notice
  • opModeIsActive
  • zeroDrive
  • roundTripEnd

Driver Station STOP ends the active program. Exit cleanup requests zero, stops vision, and closes the measurement session. Releasing the bumper is different: it pauses travel but leaves the trip available to resume. An unfinished trip is not appended as a completed result.

For example: Use bumper release for a planned pause on a clear path. Use Driver Station STOP promptly for drift, an obstruction, or stalled motion.

Think first

Can you resume the same active trip by holding the bumper after Driver Station STOP?

Show Answer

No. STOP ended that program session.

12Compare measurements with a real reference

Actual Blocks for this section
Blocks for Compare measurements with a real reference
Blocks to notice
  • roundTripReport
  • phase
  • reason
  • power
  • targetInches

Pinpoint, wheels, and the camera estimate travel in different ways. Compare their settled changes with a tape measurement in matching units and directions. Two estimates can share a scale error, so agreement alone does not replace the tape. The camera neither chooses a distance stop nor automatically fits a scale. A stationary cluster is a local reference; a tag on a moving HIVE moves too, so it is not fixed field GPS.

For example: Against 900 mm on the tape, an estimate of 914.4 mm is 14.4 mm high. At the return origin, report signed millimeters from zero rather than dividing by a zero reference.

Think first

If wheels and Pinpoint both read 914.4 mm but tape reads 900 mm, what should you investigate?

Show Answer

The difference from the independent reference, not just the agreement between sensors.

Try it without a robot

Make the math make sense

36 in × 25.4 mm/in = 914.4 mm
Convert the one-way target before comparing it with a millimeter displacement.
Pinpoint mm = (raw X − starting raw X) / 19.894367
Subtract the captured software baseline, then use the configured nominal counts-per-millimeter conversion.
wheel mm = mean(signed wheel tick changes) / 2.18
Use the forward profile's signed wheel changes with a consistent forward convention. The profile uses 2.18 ticks per millimeter.
percent error = 100 × (estimate − tape reference) / tape reference
For a nonzero reference, matching units and signs make this a useful comparison. A positive value is above the reference; a negative value is below it.
return residual = settled position − starting position
The intended return displacement is zero, so percent error would divide by zero and is undefined. Report the signed residual in millimeters instead.
camera change = settled endpoint comparison − starting comparison
Use a consistent measurement axis and profile. Raw camera range alone is not automatically chassis travel.

Use a notebook or talk through your answer with a partner. You do not need a robot to predict what these blocks will do.

1. Paper trace: count frames, then follow phases

Frame A contains IDs 30–33 and is read four times. Frames B, C, D, and E then arrive, all valid within 0.9 seconds. Trace WAIT with LEFT BUMPER released, WAIT with it held, origin capture, FORWARD, bumper release, resume, outward endpoint, settling, BACKWARD, and return settling. Write the gate, phase, and power at each step; remember that origin capture does not power forward in the same loop.

2. Work the distance and error math

Use these practice numbers: starting raw X = 1000; outward raw X = 19191.4091848; mean signed wheel change = 1955.46 ticks; tape travel = 900 mm. Calculate the 36-inch target, Pinpoint distance, wheel distance, and each percent error relative to tape. Show units and signs.

3. Find a median and a return residual

Sort practice endpoint values 908, 950, and 910 mm and find their median. Then suppose the tape return displacement is zero and the settled Pinpoint residual is +18 mm. What should you report instead of percent error? Would STOP halfway through the return settling wait make a completed trip?

Full commented Blocks program

One source program, in one column. Calls connect any named helper routines; they are not separate programs. Click a numbered blue comment to return to its explanation.

100%
Open full Blocks diagram
Back to explanationsDownload Blocks (.blk)

Ask your supervisor before importing or running these Blocks. Viewing the program does not control the robot.

Section in context

Full Blocks program

The highlighted Blocks belong to this section. You can select another blue comment.

Open full Blocks diagram
Make a change · explain the result

Try the Blocks yourself

Paper/browser logic practice only — not robot control or a physics simulation. The original native Blocks show the exact stop ordering; this practice never changes those Blocks or robot code.

Answers stay on this page only. Reset, reload, or returning to the page clears them. No saved student results.

1. Arrange the stop sequence

Put these three selected actions from the outward stopping branch in order. Other phase and telemetry updates are not shown. Use Move up / Move down with a keyboard or touch, then check your sequence.

  1. Step 1 of 3

    Set the 0.8-second settling deadline

    Native Blocks action: Set the 0.8-second settling deadline

  2. Step 2 of 3

    Zero all four drive motors

    Native Blocks action: Zero all four drive motors

  3. Step 3 of 3

    Mark the outward stop

    Native Blocks action: Mark the outward stop

2. Change the target and predict

Change the target from 36 inches to 12 inches. Calculate the millimeter target without rounding, then predict both endpoints for that 12-inch target.

Fixed formula: targetMm = targetInches * 25.4

Enter a positive number up to 1000, using a decimal point if needed; no units or rounding.

Endpoint comparisons run before the driver/sensor gates. In both scenarios, LEFTBUMPER is held and 5 valid frames satisfies the gate. Start in FORWARD.

At pinMm = 300, what happens?
At pinMm = 305, what happens?

Check your understanding

Your turn

Choose an answer, then check your thinking. You can change an answer and try again.

Your answers stay on this page and reset when you reload. No cookies, account, or saved answers.

0 / 6 correct · 0 / 6 answered

0
0
Question 1What is the default 36-inch one-way target in millimeters?

Question 2One valid camera frame contains four tags and is read five times. How many distinct frames does that provide?

Question 3During outward travel, five valid frames are recent but LEFT BUMPER is released. What does the program request?

Question 4Which measurement selects the outward distance stop in this lesson?

Question 5What happens after an endpoint stop command?

Question 6The return reference displacement is 0 mm and the settled residual is +18 mm. What should you report?

Reset clears every choice, explanation, and score.

For supervisors: 90-minute teaching plan & robot setup

Before the robot is used

Safety: This calibration has NO automatic range, stall, timeout, or sensor-disagreement motion guards. INIT ranges are display-only. Use a clear floor, measured travel and buffer space, a held-bumper operator, and a supervisor at Driver Station STOP. Keep people out of the path and buffers; STOP promptly for obstruction, drift, wrong direction, stall, or unexpected motion. Bumper release requests zero but does not eliminate coast. Isolate power before inspection.

Required hardware & dependencies

  • Four-motor drivetrain with front_left_drive, back_left_drive, front_right_drive, and back_right_drive; GoBilda Pinpoint odometry; drive encoders; Control Hub; secure battery; Driver Station and paired gamepad.
  • Front-right FORWARD; front-left, back-left, and back-right REVERSE; BRAKE and RUN_USING_ENCODER on all four. Check mounting, wiring, forward encoder signs, and Pinpoint X direction before floor travel.
  • Limelight 3A configured as limelight, a fixed camera mount, and published cluster corners. Match the 640×480 camera setting and intrinsics to the installed practice profile.
  • A stationary planar practice cluster with IDs 30–33. Each black tag is 2 inches wide; the outer black span is 9.5 inches and center gap is 1.25 inches. Measure both outer gaps and configure the matching profile; the supplied profile specifies 0.125 inches for each.
  • Tape measure, marked origin and one-way endpoint, notebook, and a clear area sized using the actual robot footprint, stopping motion, and buffers. For a 36-inch leg, 18-inch footprint, and 2-foot end buffers, about 10×6 feet is a starting layout estimate, not an automatic safety clearance.
Download Java / MyBlocks source & assets ZIPDownload technical manifest (JSON)

The ZIP contains required Java / MyBlocks helper sources and assets for an Android Studio Robot Controller project, not an APK or a standalone browser app. A supervisor must build and install the lesson-helper app, configure the hardware, then import the Blocks. These lesson OpModes are disabled by default; enable one only after completing the setup checks.

Robot setup checklist

  1. Before class, download the required helper ZIP, read INSTALL, and review the linked technical manifest. Install the required Java/MyBlocks/OpenCV/IPPE sources, libraries, and camera/profile assets in an FTC SDK 12+ Android Studio Robot Controller project. Build and install the lesson-helper app; the ZIP is not a complete APK and Blocks import does not install these dependencies.
  2. Use Upload Op Mode in the Control Hub FTC Blocks editor to import RoundTripCalibrationBlocks.blk. It is disabled by default. Resolve every missing helper and device before supervisor review and the editor's Enabled control. Select the intended mode in Driver Station; importing does not start it.
  3. With wheels safely raised, verify motor names, directions, encoder signs, Pinpoint availability, and zero INIT power; use only brief supervised sign checks. STOP before relocating to the floor. A raised-wheel check does not measure floor travel.
  4. Measure the printed black tag width, outer span, center gap, and both outer gaps. Fix the planar cluster and camera mount. Use the matching 640×480 intrinsics and practice profile and enable corner publication. A 3.25-inch field tag layout needs its own matching profile; moving HIVE tags are not stationary references.
  5. Measure floor buffers and mark the origin and default 36-inch endpoint (914.4 mm). Record battery, floor, lighting, profile, and geometry. If reviewing a shorter edited exercise, accepted targetInches values are 6, 12, 24, or 36; update tape marks and student calculations too.
  6. During INIT, inspect Pinpoint, wheel, cluster-corner and timestamp readings with power zero. Ranges are display-only. Agree on a supervisor's STOP boundary before START; there is no automatic range/stall/timeout/disagreement guard.
  7. Begin with LEFT BUMPER held only while safe and at least five distinct valid cluster frames within the last second. Check a planned bumper-release pause and gated resume. Compare completed, settled observations with tape; STOP early on any concern rather than waiting for a nonexistent timeout.

90-minute teaching sequence

  1. 0–10 min

    Discuss the opening question, assign roles, and agree on path boundaries and STOP criteria.

    Look for: Students name tape as an independent reference and understand that the motion gates are not obstacle protection.

  2. 10–25 min

    Check hardware/helper installation, signs, measured cluster geometry, matching camera profile, and floor setup.

    Look for: Zero INIT power, correctly configured devices, distinct frame timestamps, and a measured origin/endpoint with buffers.

  3. 25–40 min

    Use the Blocks walkthrough and highlighted program view. Arrange the selected stop actions, change the browser target to 12 inches, and trace the frame/phase decisions before a floor trial.

    Look for: Zero before marking the stop; 304.8 mm target with correct endpoint predictions; frame count rather than tag count; one origin retained through pauses.

  4. 40–55 min

    Work the distance, median, and error practice; discuss signed units and zero-reference residuals.

    Look for: 914.4 mm target, correct conversion denominators, signed errors, and no division by zero.

  5. 55–72 min

    With supervisor approval, make supervised repeats and record tape and settled sensor comparisons. Robot-free groups complete the phase trace and practice calculations.

    Look for: Held-bumper operation, STOP supervision, separate paused/stopped/completed notes, and measured rather than invented trial values.

  6. 72–83 min

    Compare completed records with notebook measurements and use the self-check quiz to discuss differences.

    Look for: A reasonable explanation involving scale, slip, coast, or camera geometry; completion is distinguished from matching the tape.

  7. 83–90 min

    Use STOP, make the robot safe, and discuss the exit ticket.

    Look for: Correct gates, endpoint sensor, return residual, and a named absent automatic guard.

Observation notebook

Round-trip notebook: compare settled estimates with tape
Trial / phaseTape displacement (mm)Pinpoint / wheels (mm)Camera / conditions
1 · outward settledMeasure travel from marked originRecord signed outward estimatesRecord settled comparison and recent distinct frames
1 · return settledMeasure signed return residualRecord signed residualsRecord comparison, lighting, and coast
2 · repeat or early STOPRecord measured positionRecord available estimatesRecord pause/STOP reason and whether the trip completed

Record raw starting/ending X, signed wheel changes, camera axis/profile, battery, floor, cluster dimensions, and completion state. Completed measurements go to /sdcard/FIRST/calibration_results.jsonl; use the team's approved file workflow to retrieve them. Keep early-STOP notes separate from completed trips. Compare camera changes in matching axes, not raw depth alone. Use signed residual millimeters at the zero-reference return.

Troubleshooting · stop before investigating

Missing helper blocks, assets, or camera pose output
Keep the mode disabled. Compare the helper build with the technical manifest; check SDK 12+, configured devices, required libraries/assets, 640×480 intrinsics, profile, and corner publication.
The travel phase is paused
Check held LEFT BUMPER and at least five distinct valid frames in the rolling last second. Inspect timestamps and frame validity; do not substitute tag count or bypass either gate.
Drift, wrong direction/sign, stall, or excessive coast
Use STOP promptly and isolate power. Check motor direction, wiring, Pinpoint X, forward encoder signs, traction, and buffers. The program has no automatic range/stall/timeout/disagreement motion guards.
Camera comparison jumps or disagrees with tape
Keep stopped. Recheck stationary IDs 30–33, black 2-inch widths, 9.5-inch span, center and both outer gaps, camera mount, lighting, corners, and matching profile. Do not substitute moving tags or averaged individual-tag depths for the cluster comparison.
Pause does not seem to reset the target
That is intentional: the software origin is captured once. Trace WAIT/FORWARD/BACKWARD and distinguish displayed PAUSED from the retained travel phase. Resume only when both gates pass and the path is safe.
No completed record after STOP during settling
An unfinished trip is not a completed record. Note the STOP and position separately. For a fully completed trip, check the results file through the approved file workflow and compare its measurements with tape.

Exit ticket & assessment

  1. Explain the two motion gates and why four tags in one frame are not four frame observations.
  2. Name the distance-endpoint sensor and explain how settled camera and wheel readings are used.
  3. Calculate an outward percent error, report a return residual without dividing by zero, and name one absent automatic motion guard.

Assessment: Look for a correct frame/phase trace, unit conversions, signed tape comparison, median, and return residual. Ask students to explain an error and how they would investigate it. Assess the reasoning rather than how close a sensor reading looks to the target; supervisor approval of physical operation is a separate setup decision.

Extension challenge: Plan three repeats at one target, changing only one condition. Predict how slip or a shared scale error could let sensors agree yet differ from tape. Propose an independent measurement for a later lateral-motion or turn experiment; this lesson does not automatically fit sensor scales.

Teacher key · discuss after students predict

Frames, origin, and pauses

A counts once despite four tags and repeated reads. A–E within 0.9 seconds make five valid distinct observations; LEFT BUMPER must also be held. Passing WAIT captures the origin and changes phase at zero power; a later FORWARD loop may request +0.10. Bumper/frame loss requests zero without changing the retained goal.

Distance arithmetic

36 × 25.4 = 914.4 mm. (19191.4091848 − 1000) / 19.894367 = 914.4 mm. 1955.46 / 2.18 = 897 mm. Against 900 mm tape, Pinpoint error is +1.6% and wheel error is −0.333…%. Reaching the software threshold and matching measured travel are different questions.

Median, settling, and return

Sorted values are 908, 910, 950, so the median is 910 mm. The program waits 0.8 seconds at zero and uses endpoint camera median frames after stop +0.25 seconds. Report +18 mm return residual, not percent error relative to zero. STOP halfway through return settling does not complete the trip.

Cluster geometry and reference

Four 2-inch black tags total 8 inches; 1.25 + 0.125 + 0.125 inches of gaps give a 9.5-inch span. Measure both outer gaps and use a matching profile. Camera change depends on axis, pose, and mount; moving HIVE tags are not fixed field coordinates. Tape supplies a separate comparison.

Controls and safe stopping

Pinpoint X selects ≥ target outward and ≤ 0 return endpoints. Camera and wheels compare only; there is no automatic scale fit or range/stall/timeout/disagreement protection. Clear floor, measured buffers, held-bumper operation, and a STOP supervisor remain necessary.