Source: https://mokxi.com/teachers/plans/distributed-systems-on-a-desk
Updated: 2026-11-19

Lesson plan

# Distributed systems with three boards lesson plan

Three ESP32-C3 boards on ESP-NOW: clocks, loss, retries, elections, consensus and partitions, ending in a counter that survives all of them.

4 chapters, 7 lessons, about 6 hours, on the ESP32-C3-DevKitM-1. Every lesson runs in the browser, with nothing to install.

Start a class from this course

The unit

## Objectives and materials

### By the end, students can

- Order events without a shared clock, and count what the network loses.
- Make retries safe, pick a leader, and agree on a value with a majority.
- Keep working through a partition and merge without losing a thing.
- One counter that rides out loss, crashes and partitions, and a write-up that proves it.

### Materials for the whole unit

- ESP32-C3-DevKitM-1 x 3
- LED x 3
- Resistor x 3

Every part is already on the simulator’s bench, so there is nothing to buy or hand out. The counts are the most any one lesson uses, if you build it on real breadboards too.

Chapter 1. About 1 h 40 min

## Time and messages

Order events without a shared clock, and count what the network loses.

Lesson | Time | What students do

Clocks and order Three boards, three clocks that disagree. Wall-clock stamps put a reply before its question; Lamport clocks put causes first, and a tie-break makes the order total. | 50 min

- Three boards, one air
- Lamport clocks
- Clocks that jump
- Break the tie
- What Lamport cannot see

Messages and loss Heartbeats with sequence numbers: count what arrives, lose a quarter on purpose, spot the gaps, and learn why a silent node may be dead or just unlucky. | 50 min

- Numbered heartbeats
- Lose a quarter
- Crash a node
- Dead, or just unlucky?
- Name the gaps

### Materials

- ESP32-C3-DevKitM-1 x 3
- LED x 3
- Resistor x 3

### Check for understanding

Each student finishes "Messages and loss" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Name the gaps".

Chapter 2. About 2 h 30 min

## Doing it once, and agreeing

Make retries safe, pick a leader, and agree on a value with a majority.

Lesson | Time | What students do

Retries and idempotence Two clients add to a counter on node A with acks, timeouts and backoff. Lost acks make retries count twice, until the server remembers what it has already applied. | 40 min

- Ask, wait, ack
- Lose 30 percent
- Spot the duplicates
- Make adds idempotent

Leader election The bully algorithm on three boards: heartbeats, timeouts, elections and terms, with the leader's lamp lit, and a stale leader that a term number teaches A to ignore. | 60 min

- Who leads?
- The leader's lamp
- Kill the leader
- The bully returns
- Ignore a stale leader
- Bully, ring and Raft

Consensus light Three lamps agree on one value with ballots and votes. A value commits only with a quorum, so no lamp ever shows what was not agreed, and a majority keeps going when one board dies. | 50 min

- Propose, vote, commit
- Every lamp agrees
- One board dies
- A majority is enough
- What this leaves out

### Materials

- ESP32-C3-DevKitM-1 x 3
- LED x 3
- Resistor x 3

### Check for understanding

Each student finishes "Consensus light" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "What this leaves out".

Chapter 3. About 50 min

## When the network splits

Keep working through a partition and merge without losing a thing.

Lesson | Time | What students do

Partitions A visitor count gossiped between three boards. Split the network, count on both sides, heal it, and watch a naive merge forget people until a slot-by-slot merge (a CRDT) keeps them all. | 50 min

- Count at three doors
- Split the network
- Heal, and lose people
- Merge slot by slot
- Consistent or available

### Materials

- ESP32-C3-DevKitM-1 x 3
- LED x 3
- Resistor x 3

### Check for understanding

Each student finishes "Partitions" on their own, without opening the hints. The simulator checks 5 of its 5 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Consistent or available".

Chapter 4. About 1 h 10 min

## Boss: a fault-tolerant counter

One counter that rides out loss, crashes and partitions, and a write-up that proves it.

Lesson | Time | What students do

Boss: a fault-tolerant counter The visitor counter, finished: a G-Counter gossiped between three boards that rides out loss, crashes and partitions, with an agreement lamp on each node and a read that knows when it might be stale. | 70 min

- The finished counter
- Agreement lamps
- Lose 40 percent
- Crash and catch up
- Split and heal
- A read that knows
- Write it up

### Materials

- ESP32-C3-DevKitM-1 x 3
- LED x 3
- Resistor x 3

### Check for understanding

Each student finishes "Boss: a fault-tolerant counter" on their own, without opening the hints. The simulator checks 7 of its 7 steps as they go.

Then ask each one to explain, in a sentence or two, the last thing it asked of them: "Write it up".

Your class

## Teach this unit as a class

Start a class from this course and its 7 lessons are assigned in one go, in order. Students join with a six-character code or printed login cards, and each one’s work comes back to you.

The class tools are free for 30 days for one class of up to 20 students, with no card. The lessons themselves are free either way.

Start a class from this course See the demo class

More units

## Other lesson plans

Electronics basics 20 lessons, about 10 h. Embedded on the Arduino Uno 16 lessons, about 12 h. Embedded on the ESP32-C3 13 lessons, about 11 h. Embedded on the Raspberry Pi Pico 7 lessons, about 6 h. Build your own fight stick 5 lessons, about 4 h. Embedded on the STM32F411 6 lessons, about 6 h. C++ on a board 13 lessons, about 10 h. Digital logic and memory 4 lessons, about 4 h. Interactive devices on the Uno 9 lessons, about 8 h. From gates to a computer 23 lessons, about 16 h. Build a claw machine 8 lessons, about 6 h. Every unit All the courses as ready-made units, on the teachers page.
