> For the complete documentation index, see [llms.txt](https://irseeker.buildingblockrobotics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://irseeker.buildingblockrobotics.com/updates/calibration-process.md).

# Calibration Process

{% hint style="warning" %}
The process below is specifically for the latest beta version of the IR Seeker Firmware
{% endhint %}

Your board has 12 infrared sensors in a ring that detect the pulsing light from the soccer ball. This guide walks your team through tuning them so the robot sees the ball clearly and judges its direction accurately. You only need a laptop and the ball, and the settings are saved onto the board — so you do this once, then re-do it only if things change.

## What calibration does (and why it matters)

Two things can throw off how well the robot "sees" the ball:

1. **Background IR noise** — sunlight and some lights give off infrared too, which can fool the sensors.
2. **Uneven sensors** — part of your robot (a wheel, a wall, a bracket) might sit in front of some sensors and dim the ball's light, so those directions read weaker than they should. The robot then mis-judges the ball's direction.

Calibration fixes both, using two controls on the page:

* **Detection threshold** — how bright a signal has to be before a sensor says "I see the ball." This tunes out background noise.
* **Per-sensor sensitivity (gain)** — boosts the weaker sectors so every sensor responds equally. This is what corrects for parts of your robot blocking the light.

## What you'll need

* [ ] The robot (or just the IR board) with **all DIP switches flipped UP**
* [ ] A laptop running **Chrome or Edge** (the page uses Web Serial)
* [ ] A **USB cable** from the laptop to the board
* [ ] Your **IR soccer ball**, switched **ON**, with **fresh / charged batteries**
* [ ] A piece of **string** and some tape (your distance jig — see below)
* [ ] A tape measure or ruler

## Set up the room first

Background infrared is the number-one thing that ruins calibration.

* **Block out sunlight.** Close blinds, or work in an interior room. Direct sun is full of IR and will swamp the sensors.
* **Move away from heat / IR sources** — incandescent and halogen lamps, heaters, big TVs / plasma screens. Normal LED ceiling lights are usually fine.
* **Clear other IR balls and remotes** from the area. Another team's ball or a TV remote nearby will confuse the sensors.
* **Keep people and bags back** from the board while measuring — a body or hand close to a sensor can reflect or block IR.

{% hint style="info" %}
**Quick check:** with the ball **switched off** and nothing near the board, every sensor on the screen should be **black**. If some glow, you've got background IR or your threshold is too low — fix the room first, then set the threshold below.
{% endhint %}

## The string trick — keeping the distance the same

The sensitivity step works by spinning the ball around the board and recording how strongly each sensor reads. If your distance wobbles, the readings are meaningless. A piece of string keeps the ball at a fixed radius the whole way around — it's the perfect tool for this.

1. Pick a distance that's realistic for play — somewhere around **30–50 cm** works well.
2. **Tape one end of the string to the centre of the board** (the middle of the sensor ring) so it can pivot freely.
3. Cut or mark the string so the ball sits at your chosen distance when the string is **pulled tight**.
4. Hold the ball at the end and walk it around in a full circle, keeping the **string taut** and the ball at the **same height as the sensor ring** the whole time.

A taut string gives you a perfect circle every time.

{% hint style="info" %}
Pick a distance where the sensor facing the ball lights up **strong red but not maxed out**. If a sensor shows the "saw too much" warning (flagged), move the ball a bit **farther away** and re-measure the string.
{% endhint %}

## Step-by-step

{% stepper %}
{% step %}

## Enter visualiser mode and connect

1. Flip **all DIP switches UP** and power the board.
2. Plug the USB cable into the laptop.
3. Open the [calibration page](https://irseeker-visualiser.buildingblockrobotics.com/) in **Chrome / Edge**, click **Connect**, and pick the board's port from the list.
4. The 12-sensor ring should come alive. Switch the ball **on** and wave it near the board — the sensor facing it should glow red.
   {% endstep %}

{% step %}

## Set the detection threshold

1. With the **ball off** and nothing nearby, look at the ring — all sensors should be **black**.
2. If some sensors glow on their own, **drag the Detection threshold slider up** until they all go dark. That's the noise floor.
3. Turn the **ball on** and check that the facing sensor lights up clearly. If detection feels too twitchy, nudge the threshold up a little; if it misses the ball, nudge it down.
   {% endstep %}

{% step %}

## Capture per-sensor sensitivity (the orbit)

1. Set up your **string jig** (above).
2. Click **Start capture**.
3. **Slowly orbit the ball** one full lap around the board with the string taut, pausing briefly in front of each sensor so it gets a clean head-on reading. Take about 15–20 seconds for the lap.
4. Click **Stop capture**. The page automatically sets each sensor's gain so they all respond equally — the weaker (blocked) sectors get boosted.
5. Any sensor that **never saw the ball** is left at 100% and flagged. If a sensor you expected to work is flagged, check that nothing is fully blocking it and that your orbit passed in front of it, then capture again.
   {% endstep %}

{% step %}

## Fine-tune by hand (optional)

* Hold the ball in front of a specific sensor and watch its bar. If one direction still reads low compared with its neighbours, **drag that sensor's slider up** a little until they match.

{% hint style="warning" %}
Don't over-boost. Cranking a blocked sensor too high just amplifies its noise. If a sensor is **physically** blocked, the real fix is moving the bracket or wheel — calibration can only do so much.
{% endhint %}
{% endstep %}

{% step %}

## Save to the board

* Click **Save to board**. The status should change to **✓ saved**. Your settings are now stored on the board and survive power-off.
  {% endstep %}

{% step %}

## Verify

* Walk the ball around once more and confirm the highlighted sensor and the direction arrow track it smoothly all the way around, with no dead or over-sensitive sectors.
  {% endstep %}
  {% endstepper %}

### If your board is mounted upside-down

Some robots have the board mounted flipped over (component side down). When that happens the ring is mirrored left-for-right, so the robot would think the ball is on the opposite side and chase the wrong way.

Tick **Board mounted upside-down (flip left/right)** in the Orientation section. A **⇄ Mirrored** badge appears at the top of the page, and the board reports directions correctly again in every mode.

{% hint style="success" %}
**Always check it the easy way:** hold the ball directly to the robot's **left** and make sure the display lights up on the **left**. Then check right, front and back. If left and right are swapped, toggle the setting; if they're correct, leave it. Then **Save to board**.
{% endhint %}

{% hint style="warning" %}
Only use this if the board is genuinely mounted upside-down. Setting it when it shouldn't be will make the robot chase the ball **backwards** — which is a confusing bug to track down. When in doubt, leave it off and do the left/right ball check above.
{% endhint %}

{% hint style="info" %}
Be sure to reset the DIP Switches to the SPIKE Position (1 - On, 2 - Off, 3 - Off)
{% endhint %}

## Tips & troubleshooting

| Problem                                  | Likely cause                                         | Fix                                                                |
| ---------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
| Sensors glow with no ball                | Background IR / threshold too low                    | Block sunlight; raise threshold                                    |
| One direction always reads weak          | Robot structure blocking that sensor                 | Re-run capture; boost that sensor; consider moving the obstruction |
| A sensor is flagged "saw no ball"        | Orbit missed it, or it's fully blocked               | Capture again, slower; check for a physical block                  |
| Readings jump around                     | Loose distance, low ball battery, or moving too fast | Use the string; charge the ball; orbit slowly                      |
| Sensor maxes out / flagged as too strong | Ball too close                                       | Move the ball farther; re-measure the string                       |
| Sensor never shows a reading             | Broken Sensor on the Board                           | May need a repair                                                  |

## When to re-calibrate

Redo calibration whenever:

* You **change or rebuild the robot** near the sensors (new bracket, wheel, wall).
* You **swap the ball**, or it's been a while.
* You arrive at a **new venue** (different lighting). A quick threshold check at competition is always worth it.