What this course assumes

This course is about connecting small devices to a network. It starts from the point where you can already make a board do things on its own. That needs a few working habits, and this section goes over each one.

Here is the short list. Your program checks the time instead of pausing. It is built from named situations, called states. It keeps waiting data in a small circular list. It prints notes to your computer over the USB cable. It saves a few settings so they come back after a power cut. It can run two jobs side by side. And it has a guard timer that restarts the board if the program gets stuck.

Why do these matter more now? Talking to a network is slow and unpredictable. A request can take a few seconds, or never finish. A device that simply waits would stop reading its sensor and stop responding to buttons. Each habit is a way to keep the device working while the network is being difficult.

The boards in this course are ESP32 chips, programmed in C++ through the Arduino tools. Every code box on these pages was turned into a program for two of those boards, the ESP32-S3 and the ESP32-C6, when this site was built. None of them was run.

What this course assumes is a reader who can already put firmware on a board. Concretely, that means seven skills, each refreshed in this section:

1. Timing without blocking: doing several jobs at different rates in one loop() by comparing millis() durations, never by waiting in delay().
2. State machines: writing a job as named states and the events that move between them.
3. Ring buffers: a fixed-size queue whose indices wrap around.
4. Serial debugging: printing timestamped lines over USB to see what the firmware is doing.
5. Preferences (NVS): keeping a few settings in flash so they survive a restart.
6. FreeRTOS tasks: running two jobs side by side on an ESP32.
7. Watchdogs: a timer that restarts the chip when a job stops reporting in.

The boards are ESP32s programmed in C++ with the Arduino-ESP32 core 3.3. Every sketch on these pages is compiled for the ESP32-S3 and the ESP32-C6 when the site is built, and not run. A network adds one new fact to all seven: a call that touches the network can take seconds, or never return. Each habit below is a way to keep that from freezing the rest of the device.

To go deeper on any of them, see embedded-systems, Chapters 12, 13, 15, 21 and 22.

millis() is a stopwatch that starts when the board powers up. It counts milliseconds, thousandths of a second. Your program can read it at any moment.

Say you want a reading every 2 seconds. Write down the stopwatch time when you take a reading. On every trip around loop(), the function that runs over and over, look at the stopwatch again. Has 2000 milliseconds passed since the time you wrote down? Then take a reading and write down the new time. If not, carry on with other work. Nothing ever stands still.

delay(2000) is the opposite. It freezes the whole program for 2 seconds. A button press in that time is missed.

There is one catch. The stopwatch is a fixed-size number, so after about 49.7 days it rolls over to zero, like a car's trip meter. Ask "how long since?" by subtracting, now minus then. That subtraction still gives the right answer across the rollover. Asking "is it later than then plus 2 seconds?" goes wrong right at the rollover. Always subtract.

millis() returns the number of milliseconds since the board started, as an unsigned long, a 32-bit unsigned whole number on the ESP32. A job that should run every P milliseconds keeps the time it last ran, last, and on every pass of loop() asks whether \text{now} - \text{last} \ge P. If so, it runs and sets \text{last} = \text{now}. If not, loop() moves straight on to the next job.

Two facts make this the standard pattern.

1. Nothing waits. delay(2000) holds the processor in place for 2 s. The duration test returns at once, so one loop() can serve a sensor every 2 s, a button every 10 ms and a network client as often as it needs.
2. The subtraction survives wraparound. A 32-bit counter of milliseconds wraps back to 0 after 2^{32} ms, about 49.7 days. Unsigned subtraction is arithmetic modulo 2^{32}, so now - last is still the true elapsed time across the wrap. Comparing moments, now >= last + P, is not: last + P can wrap past zero and the test fires at once, every pass.

A device meant to run for a year passes that wrap seven times, so only the duration form is acceptable.

A state machine is a way of describing a job as a short list of situations, called states, and the things that move you between them.

Take a motorized vent in a greenhouse. It can be closed, opening, open or closing. Those are its four states. It is always in exactly one of them. Things happen to it: someone asks it to open, someone asks it to close, or the motor finishes its travel. Those are events. A small table says what each event does in each state. "Open" while closed starts the motor and moves to opening. "Open" while already open does nothing.

In code, the current state is one variable. Each trip around loop() looks at it and checks whether anything should change. Nothing waits.

Connected devices use this pattern everywhere. A Wi-Fi link can be joining, connected or waiting to try again. Writing it as a state machine makes sure the device always has a way out of every situation, even when nobody is there to press reset.

A state machine describes a job as a fixed set of named states, the events that can happen, and a table that says, for each state and event, which state comes next and what to do on the way. The machine is always in exactly one state. In C++ the state is usually an enum class, and a switch on it runs once per pass of loop(), so the machine never waits either.

Connected firmware is full of these. A Wi-Fi link is joining, connected or waiting to retry. A command is received, being carried out, or done. An update is downloading, verifying or ready to boot. Writing each one as an explicit machine has two payoffs. Every state has a way out that doesn't depend on a person. And an event that makes no sense in the current state, such as "travel finished" while the vent is already open, is ignored instead of corrupting the job.

A ring buffer is a waiting line with a fixed number of seats, say 8. New items join at the back. The oldest item leaves from the front.

The trick is how the seats are reused. Picture the 8 seats in a circle. When the line reaches seat 7, the next newcomer sits in seat 0, as long as it's empty. Nothing is ever moved along. The program just remembers two numbers: which seat holds the oldest item, and how many are waiting.

Because the seats are fixed, a ring buffer never asks for more memory. That matters on a small chip that must run for months. The cost is that it can fill up. Then you must pick: turn the new item away, or throw out the oldest to make room. A device that buffers readings while its network is down faces exactly that choice.

A ring buffer is a queue stored in a fixed array of capacity N. Two numbers describe it: head, the index of the oldest item, and count, how many items it holds. A push writes at index (\text{head} + \text{count}) \bmod N and adds 1 to count. A pop reads at head, then sets \text{head} = (\text{head} + 1) \bmod N and takes 1 from count. The \bmod N is what makes it a ring: after index N - 1 the next index is 0.

The buffer never allocates memory, and push and pop take the same short time whatever it holds. When it is full (\text{count} = N), something has to give: refuse the new item, or overwrite the oldest. That choice is the firmware's to make, deliberately. Chapter 8 uses exactly this structure to hold readings while the network is down.

Some ring buffers keep a tail index instead of a count and leave one slot always empty to tell full from empty; that version holds N - 1 items. The one below holds N.

Serial is the board's way of talking to your computer through the USB cable. Whatever it prints shows up in a window on your screen, such as the Arduino IDE's Serial Monitor. Your sketch starts it once with Serial.begin(115200). The number is the speed, and the window must be set to the same one.

With a connected device, the most useful thing to print is a short note whenever something changes, with the time in front: "at 61 seconds, Wi-Fi connected." Later, when two machines disagree about what happened, those times let you match up the two stories.

Two warnings. Print when something changes, not on every trip around the loop, or the printing itself slows the board down. And never print a password. People paste these logs into help forums.

Serial sends text from the board to your computer over the USB cable, where the Arduino IDE's Serial Monitor or any terminal program shows it. Serial.begin(115200) in setup() opens it at 115 200 baud; the monitor must be set to the same rate.

For connected firmware, print events with a timestamp, not values in a tight loop. A line such as [ 61234] wifi: connected tells you what happened and when, so you can line it up against a broker's log or a packet capture later. Two rules keep logging from causing the bugs it is meant to find. Print on state changes, not on every pass, or the serial port becomes the bottleneck. And never print a password, key or token: serial logs get pasted into forums and issue trackers.

When an ESP32 loses power, everything in its working memory is gone. Some things must come back after a restart: the device's name, a correction for a sensor that reads high, or the Wi-Fi password someone typed in during setup. The chip keeps those in NVS, short for non-volatile storage. Non-volatile just means it survives a power cut.

NVS works like a small labelled filing box inside the chip's flash memory. Each value has a short label, called a key. The Arduino Preferences library lets you open a drawer, read a value by its label, and write a new one. When you read a key that was never saved, you get a default you chose instead.

Flash memory wears out a little each time it is rewritten. So save settings that change rarely. Don't save a temperature every few seconds.

An ESP32 keeps small settings in NVS (non-volatile storage), a key-value store in a partition of its flash memory. The Arduino Preferences library is the usual way in: begin(namespace, readOnly) opens a group of keys, getUInt(key, default) reads one and returns the default if it is missing, putUInt(key, value) writes one, and end() closes the group. Strings, floats and byte arrays have their own get and put functions.

Flash wears out with erasing, so NVS is for values that change rarely: a device name, a calibration offset, a count of crash restarts, the Wi-Fi credentials a user entered during setup (Chapter 4). A reading taken every few seconds does not belong there. A value that must change often is kept in RAM and saved only when it matters.

On an ESP32, your program can be split into separate jobs that run side by side. Each one is called a task. A small built-in system called FreeRTOS decides which task gets the processor at each moment. Even loop() is a task. A job that is waiting, for example for a reply from a slow server, steps aside. The other jobs keep running.

So the device can put its sensor reading in one task and its network talking in another. When the network is slow, the sensor task carries on.

The task watchdog is a guard timer. Each task it watches must check in now and then, like a night guard pressing a button on each round. If a task stops checking in, the program is probably stuck. After 5 seconds, the watchdog restarts the whole board. That is crude, but for a device in a field or on a roof, a restart is far better than sitting frozen until someone drives out to it.

The ESP32 Arduino core runs on FreeRTOS, a small real-time operating system. loop() itself runs inside a FreeRTOS task, an independent job with its own stack and a priority. xTaskCreate(fn, name, stackBytes, arg, priority, handle) starts another one. The scheduler runs the highest-priority task that is ready, and a task that calls vTaskDelay() or waits on a queue gives the processor up until it is ready again. So a sensor task can keep its schedule while a network task sits waiting for a slow server.

The task watchdog is a timer that each subscribed task must reset regularly. A task that stops resetting it, because it is stuck in a loop or waiting forever, makes the watchdog restart the chip, by default after 5 s. A task joins with esp_task_wdt_add(NULL) and reports in with esp_task_wdt_reset(). loop() is not watched until setup() calls enableLoopWDT(); after that the core resets the watchdog every time loop() returns. A restart is a blunt recovery, but for a device on a shelf far away it beats hanging until someone visits.