Face-following robot with Arduino UNO Q and Edge Impulse

Documentation Index

Fetch the complete documentation index at: https://docs.edgeimpulse.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Introduction

• MPU (Qualcomm, Linux) —> runs the ML model and control logic in Python
• MCU (STM32, Zephyr RTOS) —> drives servo PWM with real-time precision

​

What you’ll learn

• How the UNO Q’s MPU/MCU split architecture works
• Using App Lab bricks (pre-built middleware) for AI and web interfaces
• Bridge RPC communication between Python and an Arduino sketch
• Proportional steering control for differential-drive robots
• Live parameter tuning through a Socket.IO web dashboard

​

Prerequisites

​

Hardware

​

Software

• Arduino App Lab v0.6 or later (runs in-browser, no local install needed)
• A computer on the same network as the UNO Q
• Edge Impulse Studio account

​

Source code

​

Architecture overview

​

Hardware assembly

​

Chassis overview

• Two continuous-rotation servos mounted on opposite sides
• A rear caster or skid point for stability
• A top-mounted platform for the UNO Q and camera
• The USB power bank sits on or below the platform as ballast

​

Wiring

Note: The right servo is mounted mirrored relative to the left. The firmware handles this with a pulse inversion flag, no crossed wires needed.

​

Project setup in App Lab

​

File structure

detect-and-follow-robocar/
├── app.yaml              # App manifest: bricks and model selection
├── python/
│   └── main.py           # MPU application (detection + control)
├── sketch/
│   ├── sketch.ino        # MCU firmware (servo PWM)
│   └── sketch.yaml       # Build config (board, libraries)
└── assets/
    ├── index.html         # Web UI page
    ├── app.js             # Web UI logic (Socket.IO client)
    └── style.css          # Styling

​

Configuring bricks

name: Detect and follow robocar
description: Robot car that follows a target object.
bricks:
- arduino:video_object_detection:
    model: face-detection
- arduino:web_ui: {}
icon: 🚙

• video_object_detection, captures camera frames, runs the face-detection model, and delivers results to your Python code via callbacks
• web_ui, serves the HTML/JS dashboard and provides a Socket.IO server for real-time communication

​

Sketch dependencies

profiles:
  default:
    fqbn: arduino:zephyr:unoq
    platforms:
      - platform: arduino:zephyr
    libraries:
      - Arduino_RouterBridge (0.4.1)
      - Servo
      - MsgPack (0.4.2)

​

The MCU sketch: Servo control

​

Bridge RPC endpoint

#include <Arduino_RouterBridge.h>
#include <Servo.h>

Servo leftServo;
Servo rightServo;

bool set_wheel_pwm(int left_us, int right_us) {
  uint32_t left  = clamp_pulse_us(left_us);   // Clamp to 1000-2000
  uint32_t right = clamp_pulse_us(right_us);

  left  = apply_invert(left,  kInvertLeftWheel);   // false
  right = apply_invert(right, kInvertRightWheel);   // true — right is mirrored

  leftServo.writeMicroseconds(left);    // D3
  rightServo.writeMicroseconds(right);  // D6
  return true;
}

void setup() {
  Bridge.begin();
  leftServo.attach(3);
  rightServo.attach(6);
  leftServo.writeMicroseconds(1500);   // Start stopped
  rightServo.writeMicroseconds(1500);
  Bridge.provide_safe("set_wheel_pwm", set_wheel_pwm);
}

void loop() {}   // All control is event-driven via RPC

• Arduino Servo library handles PWM output via attach(pin) and writeMicroseconds(). This is more portable than the low-level Zephyr PWM API (pwm_set_dt), which depends on devicetree index mappings that can vary between board revisions.
• Bridge.provide_safe() registers the function so it runs in the Arduino loop() context, safe for hardware operations like PWM writes. Never use Bridge.provide() for GPIO/servo/motor calls, as that runs in a background RPC thread where hardware APIs can fail.
• Pulse inversion handles the mirrored right servo: inverted = 3000 - pulse. This mirrors the pulse around the 1500 us stop point, so the same “forward” command from Python moves both wheels in the same physical direction.
• Empty loop() is correct, the Bridge library hooks into the loop internally to dispatch queued provide_safe callbacks.

​

Continuous-rotation servo basics

​

The MPU application: Detection to steering

​

Brick initialization

from arduino.app_utils import App, Bridge
from arduino.app_bricks.web_ui import WebUI
from arduino.app_bricks.video_objectdetection import VideoObjectDetection

ui = WebUI()
detection_stream = VideoObjectDetection(confidence=0.5, debounce_sec=0.0)

detection_stream.on_detect_all(on_detections)
App.run()

​

Detection format

{
    "face": [
        {"confidence": 0.89, "bounding_box_xyxy": (144, 83, 234, 209)},
        # ...more faces if multiple detected
    ]
}

Important: The per-label value is always a list, even for a single detection. Code that expects a plain dict per label (without the list wrapper) will silently miss all detections.

​

Proportional steering controller

1. Find the face's bounding box center
2. Normalize to 0.0 (left edge) — 1.0 (right edge)
3. Compute heading error: (center - 0.5) x 2.0  →  range -1.0 to +1.0
4. Apply deadband (ignore small errors to suppress jitter)
5. Shape response with a power curve (compress large errors)
6. Scale by STEER_GAIN → turn speed
7. Convert to differential pulses: left = 1500 + turn, right = 1500 - turn

heading_error = (target_cx - 0.5) * 2.0
if abs(heading_error) < CENTER_DEADBAND:
    heading_error = 0.0

shaped = math.copysign(abs(heading_error) ** STEER_CURVE, heading_error)
turn = clamp(STEER_SIGN * STEER_GAIN * shaped, -MAX_TURN_SPEED, MAX_TURN_SPEED)

left_us  = speed_to_pulse(turn)    # 1500 + turn x 500
right_us = speed_to_pulse(-turn)   # 1500 - turn x 500

​

Coasting and lost target

​

Bridge communication and rate limiting

MIN_BRIDGE_INTERVAL = 0.05  # seconds

if now - _last_bridge_ts < MIN_BRIDGE_INTERVAL:
    return   # Skip this update

Bridge.notify("set_wheel_pwm", left_us, right_us)

Safety note: The emergency stop bypasses rate limiting entirely to guarantee the MCU receives the stop command immediately.

​

Watchdog

def _watchdog_loop():
    while True:
        time.sleep(0.25)
        if time.monotonic() - _last_detection_ts > NO_DETECTION_TIMEOUT:
            send_lost_target_command()

​

The web UI

​

Features

​

Deploy and run

​

App Lab GUI

1. Open Arduino App Lab in your browser
2. Create a new app or import the project files
3. Click Run, App Lab compiles the sketch, flashes the MCU, and starts the Python app

​

First boot checklist

1. Check the log for the sample_detections line, it prints the raw detection payload on the first frame. Verify:
   • The label is "face" (matches TARGET_CLASS)
   • The bounding box coordinates are reasonable for your camera resolution
2. Open the Web UI at http://<UNO_Q_IP>:7000, you should see the video stream and detection events appearing in “Recent detections”
3. Verify servos, press the Motor Test button in the UI. Both wheels should turn left, pause, then turn right. If not, check wiring and servo power before proceeding to face tracking.

​

Tuning guide

​

Steering direction

STEER_SIGN = -1.0   # Flip if left/right tracking is mirrored

​

Frame width calibration

​

Gain tuning

​

Troubleshooting