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.
- 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.
Limelight or PhotonVision
Two systems cover most of FRC. Both find AprilTags, both solve a field pose from several tags at once, and both publish it to NetworkTables. They differ in what arrives in the box.
| Limelight | PhotonVision | |
|---|---|---|
| What you buy | Sealed camera and processor, one unit | Free software, your own coprocessor and USB camera |
| Rough cost | $400 to $500 | $100 to $150 |
| Setup | Power, Ethernet, web interface | Flash the coprocessor, pick a camera, then the same |
| Tuning | Web interface only | Web interface, or your own pipeline |
| Fails when | The one unit dies, and it is one part | A camera, a cable or an SD card dies, and there are more |
This workshop uses a Limelight. The reason is scope. A PhotonVision build starts with flashing an image onto a coprocessor and picking a lens, and none of that teaches pose estimation. Everything on the next page maps onto PhotonVision with different class names.
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.
- PDH, 12 V
- A dedicated breaker on the PDH. Not the VRM, whose budget is already spoken for by the radio.
- 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.
- 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.
- 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.
- Switch the active pipeline to AprilTag. A color-blob pipeline never publishes a botpose, however well it is tuned.
- 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.
- 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.
- 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.
- 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.
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.
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 the tag size in the pipeline 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?
Why should the Limelight be powered from the PDH rather than the VRM?
What does calibrating the lens with a ChArUco board correct?
What does choosing PhotonVision over a Limelight change for the code in the next lesson?