Let the ESP32 find groups on its own with k-means clustering

Most AI needs examples with labels, but some AI finds patterns all by itself. Place points with the joystick or let the ESP32 scatter them, then watch k-means sort them into groups step by step on your phone, with coloured...
  • Level:Intermediate
  • Duration: 1 h
  • Ages 12+
  • Platform: ESP32

Tools for this lesson

Helpful for this build. Open a tool to see tips and more projects that use it.

Let the ESP32 find groups on its own with k-means clustering – EEMENTOR STEM™ lesson

In the earlier lessons of this path you always told the AI the answer: "this is red", "this is a clap", "this is a rock". That is called supervised learning. But a lot of data comes without labels, and then an AI has to find the patterns on its own. Shops use it to find groups of customers who buy similar things, streaming apps to find songs that sound alike, and astronomers to find groups of stars. This is unsupervised learning, and one of its simplest and most famous methods is k-means clustering. In this lesson the ESP32 makes its own Wi-Fi and shows a board on your phone. You place points with the joystick (or let the ESP32 scatter 30 at once), choose how many groups K you want, and press One step: you can watch every round as the points take on the colour of their nearest centre and the centres wander to the middle of their groups, until nothing changes any more.

What you'll learn

  • The difference between supervised and unsupervised learning
  • How k-means finds groups: assign every point to the nearest centre, move the centres, repeat
  • Why k-means always stops, and why the starting centres can change the result
  • Why you have to choose K yourself, and how to tell a good K from a bad one
  • How to read the joystick on the ESP32 and show live data on a web page

What you need

  • ESP32 board, expansion board and USB cable (ESP32 IoT Starter Kit)
  • Joystick module (ESP32 IoT Starter Kit)
  • A phone, tablet or laptop with Wi-Fi
  • Breadboard and jumper wires (ESP32 IoT Starter Kit)

Wiring

Breadboard wiring diagram: Let the ESP32 find groups on its own with k-means clustering
Breadboard view. Check each connection against the wiring table below.

Build it step by step

Plug in all the parts first, then add the wires in this order. In each picture the new wires are bright and the ones from earlier steps are faded. Click a picture to see it larger.

Step 1 of 2: Power rails: 3V3 and GND from the ESP32
Step 1. Power rails: 3V3 and GND from the ESP32
Step 2 of 2: Joystick: VRx → GPIO 34, VRy → 35, SW → 32
Step 2. Joystick: VRx → GPIO 34, VRy → 35, SW → 32
From To
Joystick GND GND
Joystick +5V 3V3 (on the ESP32 the joystick runs on 3.3 V)
Joystick VRx ESP32 GPIO 34
Joystick VRy ESP32 GPIO 35
Joystick SW ESP32 GPIO 32

Sensor modules from different makers can label and order their pins differently. Always follow the labels printed on your module.

The joystick's pin is labelled +5V, but connect it to 3V3: on 5 V the joystick would send up to 5 V into the ESP32's pins, which can damage them. The ESP32's analog inputs only take up to 3.3 V.

FREE

Build this circuit in EEMENTOR Lab

Wire it yourself in your browser before you touch a real wire. No sign-up, nothing to install.

The ESP32 and the parts for this lesson laid out in EEMENTOR Lab, ready to wireBuild it yourself
  1. The ESP32 and this lesson’s parts are already placed. Wire them using the wiring table above. Pins with no wire show red.
  2. Missing a part? Add it from the parts list on the left.
  3. Press Run, then try the inputs: click, hold or slide them under Selected.
  4. Wi-Fi and Bluetooth don’t run in the Lab yet, so use it to build the circuit and check the wiring before you upload the real sketch.

EEMENTOR Lab is free and in beta. Results are a guide; a real build can differ slightly. About the Lab

The sketch

No extra libraries are needed. Change AP_PASSWORD to your own password of at least 8 characters.

#include <WiFi.h>
#include <WebServer.h>

// ---------- settings ----------
const char* AP_NAME = "KMeansLab";                   // the ESP32 makes its own Wi-Fi network
const char* AP_PASSWORD = "change-me-123";           // at least 8 characters
const int JOY_X = 34, JOY_Y = 35, JOY_BUTTON = 32;
const int MAX_POINTS = 120;
const int MAX_K = 4;

float px[MAX_POINTS], py[MAX_POINTS];                // the points, from 0 to 100 on each axis
int group[MAX_POINTS];                               // which group each point belongs to (-1 = none yet)
int count = 0;
float cx[MAX_K], cy[MAX_K];                          // the centre of each group
int K = 3, steps = 0;
bool started = false, done = false;
float curX = 50, curY = 50;                          // where the joystick points
bool lastButton = HIGH;
WebServer server(80);

const char PAGE[] = R"rawliteral(<!doctype html><html><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1"><title>k-means lab</title>
<style>
body{margin:0;font-family:Arial,sans-serif;background:#F6F8FC;color:#1B3A7B;max-width:560px}
header{background:#1B3A7B;color:#fff;padding:12px 16px;font-size:20px;font-weight:bold}
canvas{display:block;width:calc(100% - 24px);margin:12px;aspect-ratio:1;background:#fff;border-radius:16px;box-shadow:0 2px 8px rgba(27,58,123,.08)}
#info{margin:0 14px;font-size:15px}
.row{display:flex;gap:8px;margin:10px 12px}
button{flex:1;font-size:15px;font-weight:bold;padding:13px 4px;border:0;border-radius:14px;background:#1B3A7B;color:#fff}
button.light{background:#E3E8F2;color:#1B3A7B} button.on{background:#DE544A;color:#fff}
</style></head><body>
<header>k-means lab</header>
<canvas id="c" width="600" height="600"></canvas>
<div id="info">-</div>
<div class="row"><button onclick="act('/add')">Add point</button><button class="light" onclick="act('/demo')">30 random points</button></div>
<div class="row"><button id="k2" class="light" onclick="act('/k?n=2')">K = 2</button><button id="k3" class="light" onclick="act('/k?n=3')">K = 3</button><button id="k4" class="light" onclick="act('/k?n=4')">K = 4</button></div>
<div class="row"><button onclick="act('/step')">One step</button><button id="run" onclick="toggleRun()">Run</button><button class="light" onclick="act('/clear')">Clear</button></div>
<script>
var COLORS = ['#DE544A', '#2F6FDB', '#1E9E5A', '#E0B000'], timer = null, last = null;
function act(u) { return fetch(u).then(function (r) { return r.json(); }).then(draw); }
function toggleRun() {
  if (timer) { clearInterval(timer); timer = null; } else timer = setInterval(function () { act('/step'); }, 700);
  document.getElementById('run').textContent = timer ? 'Stop' : 'Run';
}
function draw(d) {
  last = d;
  var c = document.getElementById('c'), g = c.getContext('2d'), s = c.width / 100;
  g.clearRect(0, 0, c.width, c.height);
  d.points.forEach(function (p) {
    g.beginPath(); g.arc(p[0] * s, (100 - p[1]) * s, 9, 0, 7);
    g.fillStyle = p[2] < 0 ? '#9AA6BD' : COLORS[p[2]]; g.fill();
  });
  d.centres.forEach(function (q, k) {
    g.save(); g.translate(q[0] * s, (100 - q[1]) * s); g.rotate(Math.PI / 4);
    g.fillStyle = COLORS[k]; g.strokeStyle = '#1B3A7B'; g.lineWidth = 4;
    g.fillRect(-14, -14, 28, 28); g.strokeRect(-14, -14, 28, 28); g.restore();
  });
  g.strokeStyle = '#1B3A7B'; g.lineWidth = 3; g.beginPath();
  g.arc(d.cursor[0] * s, (100 - d.cursor[1]) * s, 16, 0, 7); g.stroke();
  [2, 3, 4].forEach(function (n) { document.getElementById('k' + n).className = d.k == n ? 'on' : 'light'; });
  document.getElementById('info').textContent = d.count + ' points, K = ' + d.k + ' · ' +
    (d.count < d.k ? 'add at least ' + d.k + ' points' : !d.started ? 'tap One step or Run to start' : 'step ' + d.steps + (d.done ? ' · finished: no point changed group' : ''));
  if (d.done && timer) toggleRun();
}
act('/state'); setInterval(function () { if (!timer) act('/state'); }, 300);
</script></body></html>)rawliteral";

void addPoint(float x, float y) {
  if (count >= MAX_POINTS) return;
  px[count] = constrain(x, 0, 100);
  py[count] = constrain(y, 0, 100);
  group[count] = -1;
  count++;
  started = done = false;                            // new data: start again
}

// Pick K different points at random as the first centres.
void startCentres() {
  for (int k = 0; k < K; k++) {
    int i = random(count);
    for (int tries = 0; tries < 50; tries++) {
      bool used = false;
      for (int j = 0; j < k; j++) if (cx[j] == px[i] && cy[j] == py[i]) used = true;
      if (!used) break;
      i = random(count);
    }
    cx[k] = px[i];
    cy[k] = py[i];
  }
  for (int i = 0; i < count; i++) group[i] = -1;
  steps = 0;
  started = true;
  done = false;
  Serial.printf("Start: %d points, %d groups\n", count, K);
}

// One round of k-means: give every point to its nearest centre, then move each centre to the middle of its points.
void stepKMeans() {
  if (count < K) return;
  if (!started) { startCentres(); return; }
  if (done) return;
  int changed = 0;
  for (int i = 0; i < count; i++) {
    int best = 0;
    float bestD = 1e9;
    for (int k = 0; k < K; k++) {
      float d = (px[i] - cx[k]) * (px[i] - cx[k]) + (py[i] - cy[k]) * (py[i] - cy[k]);
      if (d < bestD) { bestD = d; best = k; }
    }
    if (group[i] != best) { group[i] = best; changed++; }
  }
  for (int k = 0; k < K; k++) {
    float sx = 0, sy = 0;
    int n = 0;
    for (int i = 0; i < count; i++) if (group[i] == k) { sx += px[i]; sy += py[i]; n++; }
    if (n > 0) { cx[k] = sx / n; cy[k] = sy / n; }  // a group with no points keeps its centre
  }
  steps++;
  if (changed == 0) done = true;
  Serial.printf("Step %d: %d points changed group%s\n", steps, changed, done ? " - finished" : "");
}

void sendState() {
  String j = "{\"count\":" + String(count) + ",\"k\":" + K + ",\"steps\":" + steps + ",\"started\":" + (started ? "true" : "false") +
             ",\"done\":" + (done ? "true" : "false") + ",\"cursor\":[" + String(curX, 1) + "," + String(curY, 1) + "],\"points\":[";
  for (int i = 0; i < count; i++) j += String(i ? "," : "") + "[" + String(px[i], 1) + "," + String(py[i], 1) + "," + group[i] + "]";
  j += "],\"centres\":[";
  if (started) for (int k = 0; k < K; k++) j += String(k ? "," : "") + "[" + String(cx[k], 1) + "," + String(cy[k], 1) + "]";
  server.send(200, "application/json", j + "]}");
}

void setup() {
  Serial.begin(115200);
  pinMode(JOY_BUTTON, INPUT_PULLUP);
  randomSeed(esp_random());
  WiFi.softAP(AP_NAME, AP_PASSWORD);
  server.on("/", []() { server.send(200, "text/html", PAGE); });
  server.on("/state", sendState);
  server.on("/add", []() { addPoint(curX, curY); sendState(); });
  server.on("/step", []() { stepKMeans(); sendState(); });
  server.on("/clear", []() { count = 0; started = done = false; sendState(); });
  server.on("/k", []() { K = constrain(server.arg("n").toInt(), 2, MAX_K); started = done = false; for (int i = 0; i < count; i++) group[i] = -1; sendState(); });
  server.on("/demo", []() {                          // 30 points around 3 random spots
    for (int b = 0; b < 3; b++) {
      float bx = random(15, 86), by = random(15, 86);
      for (int i = 0; i < 10; i++) addPoint(bx + random(-8, 9) + random(-4, 5), by + random(-8, 9) + random(-4, 5));
    }
    sendState();
  });
  server.begin();
  Serial.printf("Join the Wi-Fi \"%s\", then open http://", AP_NAME);
  Serial.println(WiFi.softAPIP());
}

void loop() {
  server.handleClient();
  curX = analogRead(JOY_X) * 100.0 / 4095;           // the joystick's position as 0 to 100
  curY = 100 - analogRead(JOY_Y) * 100.0 / 4095;     // up = higher on the screen
  bool button = digitalRead(JOY_BUTTON);
  if (button != lastButton) {
    if (button == LOW) {                             // press the stick: add a point where it points
      addPoint(curX, curY);
      Serial.printf("Point %d at %.0f, %.0f\n", count, curX, curY);
    }
    delay(30);                                       // wait for the contacts to stop bouncing (press and release)
  }
  lastButton = button;
}
Example screen for: Let the ESP32 find groups on its own with k-means clustering
Example screen with sample values. Yours may look different.

Try it

  1. Upload the sketch and open the Serial Monitor at 115200 baud. It tells you which Wi-Fi to join.
  2. On your phone, join KMeansLab with your password (stay connected if it says there is no internet) and open http://192.168.4.1. Move the joystick: the ring on the board follows it.
  3. Tap 30 random points. Grey dots appear in three loose clouds. With K = 3, tap One step: three diamonds appear on three of the points. These are the starting centres.
  4. Tap One step again: every point takes the colour of its nearest diamond, and each diamond jumps to the middle of its coloured points. Keep tapping and watch the colours settle. After a few steps the page says "finished: no point changed group", and the Serial Monitor shows how many points changed in each step.
  5. Tap K = 2 and Run: now two of the clouds have to share a group. Try K = 4: one cloud gets split in two. k-means always finds exactly K groups, whether they make sense or not.
  6. Tap Clear and draw your own groups: point the joystick somewhere, press it down to add a point, and add a few points close together in two or three places. Then Run. Try to fool it with one long thin group, or a tiny group next to a big one.
  7. Run the same points several times (tap K = 3 again to restart). Sometimes the result changes: it depends on which points were picked as the starting centres.

What you should see

Serial Monitor at 115200 baud showing Start: 30 points, 3 groups and steps 1 to 4 until 0 points changed, beside four phone boards from grey points to three coloured groups.

How it works

Labelled versus unlabelled points, a worked k-means step (assign P to the nearest centre, then move the centre to the mean), and K = 2, 3, 4 with an elbow chart.

k-means repeats two simple steps. Assign: for every point, measure the distance to each of the K centres and give the point to the nearest one. Update: move each centre to the average position of its points, the middle of its group. Then assign again with the new centres, update again, and so on. When a whole round passes in which no point changes group, the centres can't move any more either, and k-means stops. It always stops, because every round makes the total distance from the points to their centres smaller or keeps it the same, and it can't shrink for ever.

To start, the sketch picks K points at random as the first centres. That is why two runs on the same points can end differently: k-means finds a good grouping near where it started, but not always the best one. Real programs simply run it several times with different starts and keep the result with the smallest total distance, or choose the starting points more cleverly (a method called k-means++).

The method can't decide by itself how many groups there are: you choose K. With three clouds, K = 3 gives groups with small distances. Going from 2 to 3 makes the total distance drop a lot; going from 3 to 4 only helps a little. Data scientists draw this as a curve and look for the bend, the "elbow". k-means also likes round groups of similar size, so long thin groups or one tiny group beside a big one often get cut in the wrong place. No label was ever given, yet the ESP32 found the structure in the data on its own. Compare this with the colour detector, which needed you to tell it every colour.

Try this next

  • Show the total distance (the sum of every point's squared distance to its centre) on the page after each step, and watch it go down until k-means stops.
  • Add an "Elbow" button: run k-means for K = 1 to 4 and print the final total distance for each K. Where does the curve bend? (Allow K = 1 by changing the 2 in constrain(..., 2, MAX_K) to 1.)
  • Use real data instead of the joystick: log the temperature and the light level every minute for a day with the DHT11, and let k-means find "night", "morning" and "afternoon" on its own.
  • Make the starting centres smarter: pick the first one at random, then each next one as the point farthest from the centres chosen so far.
  • Add a fifth colour and allow K = 5.

Troubleshooting

  • The page doesn't open: check that the phone is still on KMeansLab (switch off mobile data for a moment), and type http://192.168.4.1 with http, not https.
  • The ring sits off-centre and reaches the edge too early: the joystick is on 5V, which can damage the ESP32. Unplug the USB cable at once and move the joystick's + wire to 3V3.
  • The ring drifts when you don't touch the joystick: cheap joysticks don't sit exactly in the middle. That only matters when you add points; the k-means part is not affected.
  • Pressing the joystick adds two points: the button bounces. Make the delay(30) in loop() longer, for example 80.
  • A diamond never gets any points: two centres started on the same spot, or one was squeezed out by its neighbours. Tap the K button again to restart with new random centres.
  • "add at least 3 points": k-means needs at least as many points as groups. Add points or choose a smaller K.