Gray Matter
WorkshopVision Hardware
Rough draft: nobody has reviewed this lesson yet, and it may not be how things are done this season.
LESSON 29

Vision Hardware

A camera that sees an AprilTag can tell the robot where it is standing. Everything on this page happens before any Java, and none of it can be fixed in code afterwards.

12 minutes
You’ll need
  • A robot on its wheels, with a PDH and a radio or network switch.
  • A Limelight, its mount, and an Ethernet cable.
  • A printed AprilTag from the current field map.
  • A laptop on the robot network, for the camera web interface.

Tags against drift

Odometry adds up wheel turns. Every skid, every scrubbed wheel and every millimeter of error in the wheel radius goes into the total and stays there. By the end of a match, the robot's idea of where it stands can be a meter from the truth. Nothing on the robot notices.

An AprilTag is a printed marker with an ID number. The field drawing lists where each ID sits, how high, and which way it faces. A camera measures the corners of the tag in the image and solves for the transform between camera and tag. From there it works backwards to a position on the field.

That answer owes nothing to how long the robot has been driving. It is also occasional and noisy, so it does not replace odometry. The next lesson blends the two.

The camera

This course uses a Limelight: camera and processor in one sealed unit, set up through a web page it serves itself. PhotonVision is the other common choice. It is free software on a coprocessor you buy and flash yourself, which is setup that teaches nothing about pose estimation. The ideas on the next page carry over to it with different class names.

Limelight: getting started

Mounting and wiring

Mounting decides whether any of the next lesson works, and it is the part teams get wrong. Bolt the camera where it can see the scoring tags at the moment you are scoring, not where there happened to be room.

Power
PDH, 12 V
A dedicated breaker on the PDH. Not the VRM, whose budget is already spoken for by the radio.
Network
Ethernet
Straight to the radio, or to a network switch once you have more than one device. The camera needs a real link, not Wi-Fi.
Angle
Never level
Off to one side, and above or below the tag. Dead-on and level gives the worst pose a tag can produce.

The angle rule surprises people. A tag viewed square-on and at its own height is a plain rectangle. A small error in the measured corners then swings the solved angle a long way. View the same tag from off to one side and the shape in the image carries much more information about where you stand.

Set the camera up

Do these in order, with the robot powered and the laptop on the robot network. None of the Java on the next page fixes a camera that skipped a step here.

  1. Update the Limelight OS and upload the field map. The OS goes on over USB. The map is a separate download, and it loads through the web interface. A camera running last season's map places every tag in the wrong spot.
    Limelight: downloads
  2. Switch the active pipeline to AprilTag. A color-blob pipeline never publishes a botpose, however well it is tuned. The AprilTag pipeline sets Marker Size for you. Check that it reads 165.1, the edge of an FRC tag in millimeters, and match it to your tag if you printed another size.
  3. Drop the exposure as low as it goes while the camera still finds tags. A short shutter cuts motion blur, and a blurred tag gives a wrong answer rather than no answer.
  4. Enter the camera offsets. Measure where the camera sits relative to the robot's center, and at what angle. Solving gives the camera's pose, and the offsets turn it into the robot's. Get them wrong and every measurement shifts the same way.
    Limelight: full 3D tracking
  5. Calibrate the lens with a printed ChArUco board. This corrects lens distortion, which is worst at the edges of the image. Tags sit at the edges whenever you are lined up on something.
    Limelight: ChArUco calibration
  6. Write down the camera's name. That string is the NetworkTables table the camera publishes to, and the Java on the next page addresses the camera by it. The default is limelight.
Watch out

Glue the lens

Limelight lenses are threaded and they walk under vibration. Once the focus is right for the distance you care about, put a drop of glue on the thread. A lens that shifts halfway through a competition takes the calibration with it and nothing on the driver station says so.

Check your work

Hold a printed tag about a meter in front of the camera and watch the web interface. Move it left, right, nearer and further.

Check

You should see

The tag's ID, drawn on the image and reported in the numbers below it. A distance that matches a tape measure within a few centimeters. A botpose that changes smoothly as you move the tag, rather than flickering between two answers.

Three things go wrong here. No ID at all means the pipeline is still on the wrong type, or the exposure went so low that the tag is black. An ID with a distance that is out by a factor means Marker Size does not match the tag you printed. A distance that is right up close and drifts as the tag nears the edge of the frame is the lens calibration. Run the ChArUco board again, properly this time.

Check yourself

Why does an AprilTag sighting help a drivetrain that already has odometry?

Where should a camera NOT be mounted, if you want a good pose from a single tag?

A camera reports tag IDs correctly but every pose lands about 30 cm behind where the robot really is. What is the most likely cause?

The web interface shows tag 7 at 2.4 m. Your tape measure says 1.2 m. What do you check?

What does calibrating the lens with a ChArUco board correct?

You hold a printed tag a meter in front of the camera and no ID appears on the image. What do you check first?

Pick an answer for each.