Arduino UNO Q - Ultrasonic Sensor - OLED
In this guide, you will learn how to measure distance using an ultrasonic sensor and display it centered on an OLED screen with Arduino UNO Q.
Hardware Preparation
Or you can buy the following kits:
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you.
Additionally, some of these links are for products from our own brand, DIYables .
Additionally, some of these links are for products from our own brand, DIYables .
Buy Note: If you want a bigger OLED display, use the 2.42 inch OLED Display 128x64 .
Overview of OLED and Ultrasonic Sensor
Learn about the OLED display and ultrasonic sensor in the tutorials below:
Wiring Diagram
This image is created using Fritzing. Click to enlarge image
MCU Code
The Arduino UNO Q has two processors: the STM32 MCU (handles real-time hardware control) and the Qualcomm MPU (runs Debian Linux). In this section, only the STM32 MCU is programmed — the Linux side stays idle. A later section will show how both processors work together.
/*
* This Arduino UNO Q code was developed by newbiely.com
*
* This Arduino UNO Q code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-uno-q/arduino-uno-q-ultrasonic-sensor-oled
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#define SCREEN_WIDTH 128 // OLED display width in pixels
#define SCREEN_HEIGHT 64 // OLED display height in pixels
#define TRIG_PIN 4 // The Arduino UNO Q pin connected to the ultrasonic sensor's TRIG pin
#define ECHO_PIN 3 // The Arduino UNO Q pin connected to the ultrasonic sensor's ECHO pin
Adafruit_SSD1306 oled(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);
String distStr;
void oledDisplayCenter(String text) {
int16_t x1, y1;
uint16_t width, height;
oled.getTextBounds(text, 0, 0, &x1, &y1, &width, &height);
oled.clearDisplay();
oled.setCursor((SCREEN_WIDTH - width) / 2, (SCREEN_HEIGHT - height) / 2);
oled.println(text);
oled.display();
}
void setup() {
pinMode(TRIG_PIN, OUTPUT);
pinMode(ECHO_PIN, INPUT);
if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
while (true); // halt if OLED not found
}
delay(2000);
oled.clearDisplay();
oled.setTextSize(2);
oled.setTextColor(WHITE);
distStr.reserve(10);
}
void loop() {
// generate 10-microsecond pulse to TRIG pin
digitalWrite(TRIG_PIN, HIGH);
delayMicroseconds(10);
digitalWrite(TRIG_PIN, LOW);
// measure duration of pulse from ECHO pin
long duration_us = pulseIn(ECHO_PIN, HIGH);
// calculate the distance
float distance_cm = 0.017 * duration_us;
distStr = String(distance_cm, 1);
distStr += " cm";
oledDisplayCenter(distStr);
delay(500);
}
※ NOTE THAT:
The code centers the distance text both horizontally and vertically on the OLED display.
Detailed Instructions
- First time with Arduino UNO Q? Follow the Getting Started with Arduino UNO Q tutorial to get your development environment ready before proceeding.
- Wire the components: Connect TRIG → pin 4, ECHO → pin 3. Connect OLED SDA → SDA, SCL → SCL.
- Connect: Plug the Arduino UNO Q into your computer with a USB-C cable.
- Open Arduino App Lab: Launch Arduino App Lab and wait until it detects your Arduino UNO Q.
- Create a new App: Click the Create New App button.
- Give the App a name, for example: DIYables_UltrasonicOLED
- Click Create to confirm.
- You will see a set of folders and files generated inside your new App.
- Find the sketch/sketch.ino file — this is where you will paste the MCU sketch.
Paste the sketch: Copy the MCU code above and paste it into the sketch file. Keep other files as default.
- Install the library: Click the Add sketch library button (the open book icon with a + sign) in the left sidebar.
- Search for Adafruit SSD1306 created by Adafruit and click the Install button.
Bricks
No bricks added...
Sketch Libraries
No sketch libra...
Files
python
sketch
.gitignore
README.md
app.yaml
sketch.ino
- Search for Arduino_RouterBridge created by Arduino and click the Install button.
Bricks
No bricks added...
Sketch Libraries
No sketch libra...
Files
python
sketch
.gitignore
README.md
app.yaml
sketch.ino
- Upload: Click the Run button in Arduino App Lab to compile and upload to the STM32.
- Test: Wave your hand in front of the sensor — the distance should update on the OLED every 500 ms.
※ NOTE THAT:
This code is for learning. For production, apply the noise filter from Ultrasonic Sensor tutorial.
Linux + MCU Bridge Programming
The Arduino UNO Q has two processors that work together: the MPU (Qualcomm, runs Debian Linux) and the MCU (STM32, runs Zephyr OS with your Arduino sketch). They communicate using RPC via the Arduino_RouterBridge library — never via raw serial ports.
- The ultrasonic sensor and OLED are both connected to the MCU (STM32) — sensor on pins 5/9, OLED via I2C.
- The MPU cannot control these directly — it calls Bridge.call("read_distance") on the MCU, which measures distance, shows it on the OLED, and prints it to Monitor.
- The MPU has Wi-Fi — because the MPU runs full Debian Linux with Wi-Fi, it can receive Telegram commands and trigger readings remotely.
- Communication: Bridge.call() on the Linux side invokes Bridge.provide_safe() on the MCU side (since digitalWrite() and OLED writes are hardware APIs)
- ⚠️ Reserved: /dev/ttyHS1 (Linux) and Serial1 (MCU) are used by the Arduino Router — never open them directly
In short: MPU requests reading → MCU measures distance → MCU shows on OLED and prints to Monitor.
MCU sketch — ultrasonic sensor OLED display with Bridge:
/*
* This Arduino UNO Q code was developed by newbiely.com
*
* This Arduino UNO Q code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-uno-q/arduino-uno-q-ultrasonic-sensor-oled
*/
#include "Arduino_RouterBridge.h"
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define TRIG_PIN 5
#define ECHO_PIN 9
Adafruit_SSD1306 oled(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);
String distStr;
void oledDisplayCenter(String text) {
int16_t x1, y1;
uint16_t width, height;
oled.getTextBounds(text, 0, 0, &x1, &y1, &width, &height);
oled.clearDisplay();
oled.setCursor((SCREEN_WIDTH - width) / 2, (SCREEN_HEIGHT - height) / 2);
oled.println(text);
oled.display();
}
void read_distance() {
digitalWrite(TRIG_PIN, HIGH);
delayMicroseconds(10);
digitalWrite(TRIG_PIN, LOW);
long duration_us = pulseIn(ECHO_PIN, HIGH);
float distance_cm = 0.017 * duration_us;
distStr = String(distance_cm, 1);
distStr += " cm";
oledDisplayCenter(distStr);
Monitor.print("Distance: ");
Monitor.print(distance_cm);
Monitor.println(" cm");
}
void setup() {
Bridge.begin();
Monitor.begin();
pinMode(TRIG_PIN, OUTPUT);
pinMode(ECHO_PIN, INPUT);
if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
Monitor.println("OLED init failed!");
while (true);
}
delay(2000);
oled.clearDisplay();
oled.setTextSize(2);
oled.setTextColor(WHITE);
distStr.reserve(10);
oledDisplayCenter("Ready...");
Bridge.provide_safe("read_distance", read_distance);
Monitor.println("Ultrasonic Sensor OLED Bridge ready");
}
void loop() {}
Python script (Arduino App Lab) — request distance reading from Linux every second:
/*
* This Arduino UNO Q code was developed by newbiely.com
*
* This Arduino UNO Q code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-uno-q/arduino-uno-q-ultrasonic-sensor-oled
*/
from arduino.app_utils import *
import time
def loop():
Bridge.call("read_distance")
time.sleep(1)
App.run(user_loop=loop)
- Note: Make sure Bridge.begin() is called in the MCU sketch and the sketch is uploaded before running the Python script on the Linux side.
- ⚠️ Warning: Never directly open /dev/ttyHS1 (on Linux) or use Serial1 (on MCU) in your code — these are reserved by the Arduino Router and accessing them will break the Bridge.
Detailed Instructions
- Upload the MCU sketch: Open Arduino App Lab, create a new App, paste the Bridge MCU sketch into sketch/sketch.ino, install the Adafruit SSD1306 and Arduino_RouterBridge libraries, and click Run.
- Add the Python script: Paste the Python code above into the Python tab of the same App.
- Run the App: Click Run — Python requests a reading every second; MCU updates the OLED and Monitor.
- Check the console: Open the Console tab → MCU Monitor subtab to see the distance values.
App Lab Console Output
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
Ultrasonic Sensor OLED Bridge ready
Distance: 29.4 cm
Distance: 27.6 cm
Distance: 14.3 cm
Telegram Integration
Read the distance and display it on the OLED remotely via Telegram.
If you do not have a Telegram bot yet, see How to Create a Telegram Bot to get your bot token before continuing.
MCU sketch: Keep the same MCU sketch from the previous Bridge section — no changes needed. Make sure it is already uploaded and running on the STM32 before proceeding.
Python script (Arduino App Lab) — Telegram bot for ultrasonic OLED display:
/*
* This Arduino UNO Q code was developed by newbiely.com
*
* This Arduino UNO Q code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-uno-q/arduino-uno-q-ultrasonic-sensor-oled
*/
from arduino.app_utils import *
import requests
import time
BOT_TOKEN = "YOUR_BOT_TOKEN"
API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
last_update_id = 0
def send_message(chat_id, text):
requests.post(f"{API_URL}/sendMessage", json={"chat_id": chat_id, "text": text})
def get_updates():
global last_update_id
resp = requests.get(f"{API_URL}/getUpdates", params={"offset": last_update_id + 1, "timeout": 5})
return resp.json().get("result", [])
def loop():
global last_update_id
updates = get_updates()
for update in updates:
last_update_id = update["update_id"]
msg = update.get("message", {})
chat_id = msg.get("chat", {}).get("id")
text = msg.get("text", "").strip()
if text == "/read":
distance = Bridge.call("read_distance")
send_message(chat_id, distance)
else:
send_message(chat_id, "Commands:\n/read — measure distance and display on OLED")
time.sleep(0.5)
App.run(user_loop=loop)
- Note: Replace YOUR_BOT_TOKEN with the token obtained from @BotFather on Telegram.
- Send /read to trigger a distance measurement — the result appears on the OLED and in Monitor.
Detailed Instructions
- Upload the MCU sketch: Use the Bridge MCU sketch from the previous section (upload it first if not already done).
- Paste the Telegram script: Copy the Python code above into the Python tab of your App in Arduino App Lab.
- Set your token: Replace YOUR_BOT_TOKEN in the script with your actual bot token.
- Run the App: Click Run — the bot starts listening for Telegram messages.
- Test it: Send /read — the bot replies with the measured distance, which also appears on the OLED.
App Lab Console Output
sketch.ino
1#include "Arduino_RouterBridge.h"
Serial Monitor
Python
[2026-04-29 12:00:01] Telegram: /read
[2026-04-29 12:00:01] Distance: 29.4 cm
[2026-04-29 12:02:05] Telegram: /read
[2026-04-29 12:02:05] Distance: 13.1 cm
Telegram
12:45
Welcome to Telegram!
ArduinoBot
10:19
Chatting with Arduino...
BotFather
Yesterday
Your bot has been created.
ArduinoBot
bot
OpenClaw Integration
OpenClaw integration for Arduino UNO Q ultrasonic sensor with OLED is coming soon.
- Coming Soon: OpenClaw support for this project on Arduino UNO Q will be covered in a future update.
Application/Project Ideas
- Portable range finder: Use sensor + OLED as a handheld distance-measuring tool
- Parking assistant: Display a bar-graph of remaining space as a vehicle backs toward a wall
- Water tank level meter: Display the current water level on the OLED in real time
- Robot proximity gauge: Show the current obstacle distance on an onboard OLED screen
- Measuring station: Mount on a wall to display live room dimensions for home renovation projects
Challenge Yourself
- Easy: Show "CLOSE!" on the OLED in large text when distance < 20 cm
- Medium: Draw a bar graph on the OLED that fills as the object gets closer
- Advanced: Send the actual distance value (in cm) directly back to the Telegram user as a message