Ultrasonic Distance

Name: Ultrasonic Distance
Author: Synthiam

Displays HC-SR04 ultrasonic distance readings in ARC; scriptable via GetPing(), pausable, sets a variable with multiplier, optional NMS output

Hardware Info

How to add the Ultrasonic Distance robot skill

Load the most recent release of ARC (Get ARC).
Press the Project tab from the top menu bar in ARC.
Press Add Robot Skill from the button ribbon bar in ARC.
Choose the Ultrasonic category tab.
Press the Ultrasonic Distance icon to add the robot skill to your project.

Don't have a robot yet?

Follow the Getting Started Guide to build a robot and use the Ultrasonic Distance robot skill.

How to use the Ultrasonic Distance robot skill

What this skill does: Shows the distance reading from an ultrasonic sensor connected to an EZB.
What this skill does NOT do: It does not automatically steer, stop, or avoid obstacles. For navigation/avoidance, use the Ultrasonic Radar skill.

Ultrasonic sensors measure distance using sonar (sound navigation ranging)—they send out a quick burst of sound and listen for the echo. The time it takes for the echo to return is used to estimate how far away an object is. This is similar to how bats and dolphins “see” with sound.

Good to Know (Beginner Tips)

Works well on hard surfaces (walls, wood, plastic, boxes).
Less reliable on soft or angled surfaces (fabric, carpet, curtains, plush items) because they absorb or deflect the sound.
Unlike many IR sensors, ultrasonic sensors are generally not affected by sunlight or black materials.
Temperature and voltage can affect readings (sound travels differently in warm vs. cold air).

When an HC-SR04 (or equivalent) Ultrasonic Distance Sensor is wired to your EZB and configured in this skill, the skill will display a distance value for whatever is directly in front of the sensor.

How Readings Work (Important)

The value shown by this skill is typically 0–255. This number is a raw sensor value and is not automatically “cm” or “inches”. The raw value can vary depending on the sensor model, input voltage, the surface you’re detecting, and even room temperature.

If you need real-world units (cm/in), use the Multiplier setting or calibrate with a tape measure by comparing “value on screen” vs. “actual distance”.

Main Window

What You See

1. Ultrasonic Distance Value

Shows the current distance reading (usually 0–255).
Higher/lower values represent farther/closer objects depending on sensor and configuration.

2. Bar Display

A quick visual way to see changes in distance without watching the number.
Helpful for testing wiring and sensor direction (point it at a wall and move closer/farther).

3. Pause Checkbox

When checked, the skill stops continuously sampling the sensor.
This is useful if you only want readings on demand from a script (see next section).

Using This Skill with Scripts (GetPing)

This skill integrates with ARC scripting. If the Pause checkbox is checked, the skill will not constantly poll the sensor. Instead, it will update when your script calls GetPing() (as long as the skill’s configured ports match your wiring).

Why pause + GetPing() is useful

Reduces unnecessary communication traffic to the EZB.
Lets you control exactly when a reading is taken (for example, only when the robot is moving forward).
You can keep the skill paused permanently and still see updated values whenever GetPing() is called.

Settings

Sets the name shown on the skill’s window. You can rename it to match where it’s installed (example: “Front Ultrasonic”).
Note: Changing the title also changes the name used in the controlCommand() reference for this skill.

Choose which EZB you are using (example: EZB #0). If you only have one EZB connected, it is usually 0.

Trigger port: the digital pin used to send the ultrasonic “ping”.
Echo port: the digital pin used to listen for the returning echo.
3-wire sensors: some combine trigger/echo into one signal wire—when using that type, set Echo to the same port as Trigger (as required by the sensor design).

Controls how often the skill samples the sensor (in milliseconds). Range: 100–60000 ms. Default: 250 ms.

Smaller number = faster updates (more frequent readings).
Larger number = fewer updates (less traffic and CPU usage).

Variable

Stores the most recent reading into a variable automatically.
This can reduce the need to call GetPing() repeatedly, which can add unnecessary communication overhead.

Multiplier

Scales the raw value into a more useful unit.
Example: the default multiplier of 1.25 is commonly used to convert the reading into centimeters (depending on the sensor and setup).
For best accuracy, calibrate: measure a known distance with a tape measure, compare to the raw value, then adjust the multiplier until it matches.

Optionally pushes distance data into the NMS (Level #3, Group #1) so other navigation skills (such as The Navigator) can use it. If you are new, you can leave this disabled until you start working with navigation behaviors. Use the ? help icons in ARC and the NMS manual for details on each option.

Wiring Diagram

Ultrasonic distance sensors commonly come in two styles: 3-wire (trigger+echo combined) and 4-wire (separate trigger and echo). Some versions include a voltage regulator (inline or built-in).

Voltage reminder:
If your ultrasonic sensor has a regulator, it typically needs +6V or higher (often connected to Vin).
If it does not have a regulator, it typically needs +5V.

3-wire Wiring (with built-in regulator)

Ground: Black wire to GND
Power: Red wire to Vin
Trigger/Echo: White wire to a Digital pin

4-wire Wiring (with regulator)

Ground: Black wire from regulator to GND
Power: Red wire from regulator to Vin
Trigger: White wire to a Digital pin
Echo: Green wire to a second Digital pin

Beginner Troubleshooting Checklist

No reading / stuck value: confirm GND and power wiring, then confirm the configured digital ports match where you plugged in trigger/echo.
Reading seems random: try changing the Interval to a slower value (e.g., 500–1000 ms), and test with a flat wall 30–100 cm away.
Always detects “something”: check for nearby surfaces that could reflect sound (robot body panels, brackets), and see the “Fix Resolution” section below.
Inconsistent on fabric: test with a hard surface; fabric often absorbs sonar.

Fix Resolution (False Positives on Some Housings)

If you use an EZ-Robot ultrasonic distance sensor, you may occasionally see false positives caused by the ping echoing inside the sensor casing. A common fix is placing a few small cotton balls inside the case around the sensors to dampen internal reflections.

Tech Details (Video)

Resources

Synthiam’s ultrasonic hardware reference design is available here.

Similar Skills

Upgrade to ARC Pro

Stay at the forefront of robot programming innovation with ARC Pro, ensuring your robot is always equipped with the latest advancements.

Compare Pro Features View Subscription Plans

Jeremie

PRO

Canada

#81 Oct 2022

Here are the results:

15cm Good

15cm Bad

30cm Good

30cm Bad

100cm Good

100cm Bad

Infinite Good

Infinite Bad

They look very similar to each other. I am baffled.

DJ Sures

PRO

Synthiam

#82 Oct 2022

Hahaha, now that is funny because they're acting the same! I believe you found some sentient distance sensors that do not want to be discovered.

How about the time between trigger and echo?

DJ Sures

PRO

Synthiam

#83 Oct 2022 — Edited Oct 2022

Okay, here's the code for the EZB's ping sensor.


uint16_t HC_SR04(uint8_t triggerPort, uint8_t echoPort) {

  uint16_t cnt = 0;  

  Output_Drive(triggerPort);

  Output_High(triggerPort);

  DelayCycles(185);

  Output_Low(triggerPort);
  
  Output_Float(echoPort);

  while (true) {

    if (Read_Digital(echoPort))
      break;

    if (cnt == 2000)
      return 255;

    cnt++;
  } 

  cnt = 0;

  while (true) {

    if (!Read_Digital(echoPort))
      break;
     
    if (cnt == 40000)
      return 255;

    cnt++;
  }

  return cnt / 156.8627451;
}

The first WHILE loop is waiting for the start of the ECHO pulse. The second WHILE loop is waiting for the end of the ECHO pulse. Both have a timeout. Essentially, the WHILE loops together are the replacement for Arduino's "pulseIn()" command.

The part that i bolded (first WHILE loop) will matter if the sensor takes too long to return before receiving the start of the echo pulse. So if you can check the time between trigger and echo - that would probably tell us what's going on with the knockoffs

Jeremie

PRO

Canada

#84 Oct 2022 — Edited Oct 2022

Sorry, no screenshots this time but I believe you have found the culprit!

Bad trigger to Echo separation is 2.25mS

Good trigger to Echo separation is 500uS

Looks like the arrival time of the Echo is way slower on the bad sensors.

*Edit: If anyone is curious, I found the main chips used on these sensors: RCWL-9300 (Microcontroller), RCWL-9206 (Communication IC), LM324 (Quad Op-Amp)

Some of the good sensors have SGM324 (Quad Op-Amps)

DJ Sures

PRO

Synthiam

#85 Oct 2022 — Edited Oct 2022

Yeah, that's it. So the knockoff sensors are super slow and timeout. That's a good thing we discovered because the ping sensor is a blocking function on microcontrollers and will pause all communication while waiting for the echo pulse to complete. Those sensors would make any robot super duper slow because there would be a >2ms delay for every reading. Wow, those are terrible sensors. Two milliseconds in electronics is forever, specifically when blocking communication or other I/O commands. A slow sensor would result in robots driving into walls because it can't send communication fast enough while it waits for the sensor readings to complete.

I'm guessing the microcontroller programmers of the knockoff sensors didn't know how to write the code efficiently. So their code takes too long to execute and blocks for >2ms.

While Arduino's "pulseIn()" on the Arduino EZB Firmware will wait up to 3 minutes, it would work with the knock-off sensors. However, I would not recommend it because the blocking time waiting for an echo will cause significant performance issues.

TMesserschmidt

USA

#86 Oct 2022

DJ,

You're welcome. You'll get my bill.

Thomas

DJ Sures

PRO

Synthiam

#87 Oct 2022

What am I welcome for?

TMesserschmidt

USA

#88 Oct 2022

For thanking me for finding the issue. I told you that you would need to hire me one day .

Ultrasonic Distance

How to add the Ultrasonic Distance robot skill

Don't have a robot yet?

How to use the Ultrasonic Distance robot skill

Good to Know (Beginner Tips)

How Readings Work (Important)