Ranger 8-Way (TOF8) × SPIKE × Official LEGO App

This page covers Official LEGO App (SPIKE 3, Robot Inventor) only: how to set it up for the Ranger 8-Way (TOF8) on SPIKE Prime / Robot Inventor, how to read every value, the commands it supports and examples. Use the switcher above to change product, host or software.

Setup

What you need

• Sensor: Ranger 8-Way (TOF8) (SPIKE edition). Each platform is a different factory edition; an EV3 edition is not recognised on a SPIKE hub.
• Hub: SPIKE Prime (Education, yellow hub) or Robot Inventor (home edition, teal hub).
• Cable: the standard cable in the box, or an original LEGO cable.
• Software: Education uses the LEGO Education SPIKE App (the examples on this site use SPIKE 3); the home edition uses the LEGO MINDSTORMS Robot Inventor App.
• Hub firmware: the original LEGO firmware. No need to switch to Pybricks.

Install the software

1. Education: install the SPIKE App from the LEGO Education download page.
2. Home edition: install the LEGO MINDSTORMS Robot Inventor App.
3. If the hub has been flashed with Pybricks, switch it back to the original LEGO firmware with the SPIKE App first, or the official App cannot connect.

Note

The Education and home editions read values differently: in the home-edition App some blocks are limited to 0 ~ 126, and "Color" only goes up to 10. Use the readings for the edition you have.

Make the software see the sensor

No extension and no driver needed. Plug the sensor into the hub and the official App treats it as an original LEGO sensor (for most products a SPIKE Color Sensor); just use that sensor's blocks.

• An official block returns one number at a time, so the product data is encoded into the "Color", "Reflected light" and "Raw red / green / blue" slots. See the readings below for what each slot means.
• To open an example: download the .llsp3 (home edition: .lms) → open the App → top-left "File" → "Open" → pick the file.

Wiring

1. Plug the sensor into hub port C with the cable (any of A~F works; choose the same port in your program).
2. The plug only goes in one way: latch up, push it in gently, do not force it.
3. When the hub is on, the light on the sensor comes on.

Wait 2~4 seconds after power-on

The Ranger 8-Way needs no calibration; plug it in and go. After power-on, wait 2~4 seconds for the 8 lasers to get ready; meanwhile everything reads 120 (cm). Start your program with a short wait before reading distances.

The table assumes the sensor faces forward with the components up. Put your hand on the robot's left: example 1 should show a negative direction. If it shows a positive one, the sensor is mounted the other way, and "turn left" / "turn right" in the examples must be swapped too.

Warning

The official App readings are worked out from the sensor firmware and have not yet been checked one by one on a real hub. The home edition (Robot Inventor) uses a different format, so the official App examples on this page do not apply to it. If official-App example 1 always shows -7 or odd numbers wherever your hand is, switch to the MBC Blocks website or Pybricks and let us know.

First test

1. Connect the hub to the App over USB or Bluetooth.
2. Open example 1 on this page and press Run.
3. Move your hand or the mat in front of the sensor: if the number changes, everything is connected.

FAQ

• Nothing happens when I plug it in? Check in order: both ends of the cable firmly in → another hub port → another cable → another hub.
• Different Apps give different numbers? The Education (yellow hub) and home (teal hub) editions use different formats. Check which edition you have and use its readings.
• Do I need an adapter or a driver? No. The connector and protocol are the same as a LEGO hub port; it is recognised automatically.
• Example 6 won't open in the official App? Examples marked "Pybricks only" use a new mode in firmware from 2026-10 on, which the official App blocks cannot read.

Reading values

The official app shows the sensor as a Color Sensor. Read it with the color, reflected light and raw red / green / blue blocks under More Sensors, then decode as shown.

sensor 1~8 distance (cm) distCm

Range	Meaning
0~120 cm	distance of each sensor 18, 0120 cm (1 = far left, 4 and 5 = front, 8 = far right, 30° apart); 120 = nothing that way / sensor failed; ids 10~17

Hub	Value	Block (More Sensors → Color Sensor)	Decode
SPIKE Prime	group 1	「color」	the number it returns
SPIKE Prime	group 2	「reflected light」	the number it returns
SPIKE Prime	group 3	「raw red」	the number mod 256
SPIKE Prime	group 4	「raw red」	floor(the number ÷ 256)
SPIKE Prime	group 5	「raw green」	the number mod 256
SPIKE Prime	group 6	「raw green」	floor(the number ÷ 256)
SPIKE Prime	group 7	「raw blue」	the number mod 256
SPIKE Prime	group 8	「raw blue」	floor(the number ÷ 256)
Robot Inventor	group 1	「reflected light」	the number it returns
Robot Inventor	group 2	「color」	the number it returns

Firmware note: 16 B = [第 1~8 顆, 0×8]：App 顏色 = 第 1 顆、反射光 = 第 2 顆、原始紅 = 第 3+256×第 4 …; byte0/1 = 第 1、2 顆 ×10/120（0~10）；byte2~7 = 第 3~8 顆兩顆一組 4-bit 再查表編碼（spikeEncodeU8，INO:259-284）

Not readable here：nearest distance (cm), nearest direction, farthest distance (cm), farthest direction, front distance (cm), nearest distance (mm), init bitmap, fault bitmap, front distance (mm), sensor 1~8 distance (mm). Use MBC Blocks website / Pybricks for these.

Examples

Example 1: Which direction is the nearest thing

What this example does: the hub display shows which direction the nearest thing is in (-7 to 7). Hand on the left shows a negative number, straight ahead shows 0, on the right shows a positive number; nothing around shows ✕.

What you need

• 1 SPIKE hub
• 1 Ranger 8-Way
• Your hand (or a book)

How to connect: plug the Ranger 8-Way into port C.

Download the program

Step by step: what the program does

1. Repeat forever: the blocks inside keep running until you press stop.
2. Read the nearest distance and direction: the MBC Blocks website and Pybricks have "nearest target distance" and "nearest target direction" directly. In the official App you build it yourself, in 3 parts:
   • Read the 8 channels: following the table above, split the 5 blocks into 8 variables, "ch1" to "ch8".
   • Compare channel by channel: start by assuming the "nearest distance" is 120 and the "nearest channel" is 0; then go from channel 1 to channel 8, and if this channel is closer than the "nearest distance", remember it. After the comparison, "nearest channel" is the closest channel (it stays 0 if nothing is there).
   • Convert to a direction: direction = channel × 2 − 9 (channel 1 → -7, channel 4 → -1, channel 5 → 1, channel 8 → 7).
3. If nothing is there (MBC Blocks website and Pybricks: nearest distance ≥ 120; official App: nearest channel = 0) → show ✕.
4. Else → show the direction on the display. The MBC Blocks website and Pybricks also print the direction and distance on the computer screen.

What you should see when it runs

• Nothing around: ✕.
• Hand 30 cm to the far left: -7; front-left: -5 or -3.
• Hand straight ahead: 0 (the official App version shows -1 or 1, because it picks only one channel, and both channels 4 and 5 point straight ahead).
• Hand on the right: a positive number.

Common questions

• Left and right are swapped? → Your sensor is mounted the opposite way from the table (for example upside down), so you will need to swap the left and right turns in the later examples too.
• It always shows ✕? → Wait 2 to 4 seconds after power-on; or your hand is too far away (over 120 cm), or the object is black/transparent.
• The MBC Blocks website shows even numbers (for example -6, -2)? → That's normal. When your hand is right between two channels and both see it, the direction is averaged.
• It shows the same number wherever my hand is? → One channel may be broken or blocked and keeps reading a very small number. Check with the "channel N OK" block on the MBC Blocks website or laser8.is_ok(1) to is_ok(8) in Pybricks.

Example 2: Change the light when something gets close

What this example does: when something gets close in any of the 8 directions, the hub light changes: yellow within 50 cm, red with beeping within 20 cm, green when nothing is near. Like a parking sensor.

What you need: same as Example 1.

How to connect: plug the Ranger 8-Way into port C.

Download the program

Step by step: what the program does

1. Read the nearest distance: the official App uses the "read 8 channels + compare channel by channel" blocks from Example 1; the other two read "nearest target distance" directly.
2. If nearest distance < 20 → red light and a beep.
3. Else, if nearest distance < 50 → yellow light.
4. Otherwise → green light.
5. Wait 0.1 seconds, then check again.

What you should see when it runs: move your hand in slowly from far away, and the light goes green → yellow → red (beeping). It changes the same way when your hand comes in from the left or the right.

Common questions

• Why check < 20 first, then < 50? → 15 cm is also "less than 50". If you checked < 50 first, the red light would never come on. Write the conditions starting from the strictest one.
• It turns green when my hand touches the sensor? → When something is extremely close (within a few cm), the laser may not be able to measure it and reads 120. Leave a little gap.
• It stays yellow when sitting on the desk? → The side channels are seeing other things on the desk, or the sensor is mounted too low and sees the desktop.

Example 3: Turn to face the nearest thing

What this example does: the robot turns on the spot so its front faces the nearest thing (within 60 cm). Hand on the left → it turns left; on the right → it turns right; once it is facing you, it stops.

What you need

• Everything from Example 1, plus
• A two-wheeled robot car (two motors as the wheels)

How to connect

• Plug the Ranger 8-Way into port C, mounted at the front of the car, with channels 4 and 5 pointing straight ahead, at least 5 cm off the floor
• Left wheel motor on E, right wheel motor on F

Download the program

Step by step: what the program does

1. Tell the hub where the wheels are: in the official App it is "set movement motors to E+F" at 20% speed; on the MBC Blocks website and in Pybricks it is "drive base: left wheel E, right wheel F".
2. Read the nearest distance and direction (in the official App, the "nearest channel").
3. If nearest distance > 60 → too far or nothing there → stop and wait.
4. Else, if the thing is on the left (direction < -1; official App: channels 1 to 3) → turn left on the spot.
5. Else, if the thing is on the right (direction > 1; official App: channels 6 to 8) → turn right on the spot.
6. Otherwise (straight ahead) → stop.

What you should see when it runs: put your hand on the robot's left and it turns to face your hand; walk slowly around it and it keeps turning to follow you.

Common questions

• It overshoots and wobbles from side to side of my hand? → It is turning too fast. MBC Blocks website and Pybricks: make the "90" smaller (for example 60); official App: lower the 20% speed (for example 15%).
• It turns the wrong way and gets farther off? → Go back to Example 1 and confirm left and right; or the motors are mounted the other way round (see the common questions in Example 4).
• It never stops turning? → A nearby wall or table leg is closer than your hand, so it goes after the wall. Play in an open area.

Example 4: Avoid obstacles by heading for the most open side

What this example does: the robot keeps driving forward. When something is within 30 cm straight ahead, it stops, checks which side is more open, turns 45 degrees that way, then keeps going.

What you need: same as Example 3, plus an open floor area with a few boxes as obstacles.

How to connect: plug the Ranger 8-Way into port C, mounted at the front; left wheel motor on E, right wheel motor on F.

Download the program

Step by step: what the program does

1. Set up the wheels and speed: 30% in the official App; 150 mm per second in the other two.
2. Repeat forever: check whether channel 4 or channel 5, the ones pointing straight ahead, reads less than 30 cm.
3. If yes → stop, then find the most open direction:
   • The MBC Blocks website and Pybricks read "most open direction" directly: negative (the left is more open) → turn left 45 degrees, otherwise turn right 45 degrees.
   • The official App uses the same "compare channel by channel" as Example 1, but looks for the farthest channel instead: channels 1 to 4 → turn left, channels 5 to 8 → turn right. The official App's 45-degree turn is "move 0.25 rotations with steering -100 (or 100)", which is roughly 45 degrees on the standard LEGO car.
4. Else → drive forward.

What you should see when it runs: the car drives forward, stops just before hitting a box, turns toward the more open side, then carries on. In a corner it keeps turning until it finds a way out.

Common questions

• It only stops after bumping into the obstacle? → Too fast, or the obstacle is black/transparent. Lower the speed, or raise the "30".
• It clips things on the side? → This example only looks at the two front channels. For extra safety, add channels 3 and 6 to the "or" so they are checked as well.
• It turns toward the opposite side from the open one? → Go back to Example 1 and confirm left and right; if they are swapped, swap the left and right turns.
• The car drives backward / the direction is reversed? → The motors are mounted the opposite way from the standard LEGO car. Official App: mount the motors the way the LEGO "standard driving base" does; MBC Blocks website: in the "drive base" block, flip the "forward" direction of both the left and right wheel; Pybricks: change the left wheel to Direction.CLOCKWISE and the right wheel to Motor(Port.F, Direction.COUNTERCLOCKWISE).
• What happens if one channel is broken? → A broken channel always reads 120, so it gets treated as "the most open", and the robot may turn toward an obstacle. Check each channel using the common questions in Example 1.

Example 5: Follow your hand

What this example does: the robot follows your hand and keeps a distance of 15 to 25 cm: when your hand is a bit far (25 to 60 cm) it drives forward while steering toward your hand; at just the right distance it stops; too close (under 15 cm) it backs up; hand taken away (over 60 cm) it stops.

What you need: same as Example 3.

How to connect: plug the Ranger 8-Way into port C, mounted at the front; left wheel motor on E, right wheel motor on F.

Download the program

Step by step: what the program does

1. Read the distance and direction of your hand (the nearest thing) (the official App uses the blocks from Example 1).
2. Split it into 4 cases by distance, checked from top to bottom:
   • > 60 cm → can't see the hand → stop.
   • < 15 cm → too close → back up (MBC Blocks website and Pybricks: 80 mm per second).
   • > 25 cm → a bit far → drive forward, and steer as much as the hand is off center: the MBC Blocks website and Pybricks turn at "direction × 15" degrees per second; the official App's steering is "direction × 10" (direction is still channel × 2 − 9).
   • Everything else (15 to 25 cm) → just right → stop.

What you should see when it runs: put your hand 40 cm in front of the robot and it drives forward; move your hand to the left and it turns left while driving; hold your hand still and it stops about 20 cm away; push your hand toward it and it backs up.

Common questions

• It keeps jittering back and forth? → The "just right" range is too narrow. Change 15 to 12 and 25 to 30.
• It steers too sharply / too slowly? → Change the "× 15" number (the official App uses "× 10"): bigger turns faster, smaller turns slower.
• It follows the wall instead of my hand? → Something nearby is closer than your hand. Play in an open area where your hand is the nearest thing.
• The official App version doesn't back up? → Make sure the direction on the "start moving" block is the "backward" arrow.

Note

These examples have no version for this software: Example 6 (advanced): How many millimeters away is the nearest thing

More questions

• The hub does not detect the sensor? Unplug and replug, wait 2 s, try another port. The official app shows it as a colour sensor — that is expected.
• Can I use the official app and Pybricks on the same hub? One firmware at a time: Pybricks and the MBC Blocks website need Pybricks firmware, the official app needs LEGO firmware; you can switch back any time with the SPIKE app.

Still stuck? Contact us with your software and a screenshot of the program.

Downloads

• Download centre (libraries, firmware, catalogue for every product)

Sources

• Host and software list：_build/guides.json
• Values and commands：_build/protocol/tof8.json (single source of truth)
• Setup：_build/guides/software/spike-official.en.md、_build/guides/product/tof8/spike-official.en.md
• Examples：sensors/tof8/spike-examples.md