DEV Community: Yunus Emre Güzel

Why Your C Program Prints a Garbage Value (and How to Fix It)

Yunus Emre Güzel — Tue, 27 Oct 2026 13:27:47 +0000

The Problem: Your printf Shows a Random Number

You declare a variable, print it before assigning anything, and get a number that looks like it came from nowhere:

#include <stdio.h>

int main(void) {
    int total;
    printf("Total: %d\n", total);
    return 0;
}

Run it and you might see Total: 32764. Run it again and it might say Total: -1073745472. Change nothing, rebuild, and it can be a third number.

That is a garbage value: whatever happened to be sitting in that memory before your program claimed it. It is not random in the sense of being generated — it is leftover data from something that ran earlier.

Why It Happens: Memory Is Not Cleaned for You

When you write int total;, C reserves four bytes for it. That is all it does. It does not write zero into them.

Those four bytes already have a value — whatever the previous owner left there. Your program, the C runtime, or the operating system used that memory a moment ago. C hands it to you as-is because zeroing every variable would cost time, and C is built to be fast.

So the number you see is real data, just not yours. That is why it changes between runs: the memory layout differs each time.

The Fix: Initialise When You Declare

Give the variable a value at the moment you create it:

int total = 0;
double average = 0.0;
char grade = '\0';

Now printf("Total: %d\n", total); prints Total: 0 every time, on every machine.

This is not optional politeness. It is the difference between a program that works and one that works on your computer today.

The Trap That Bites Harder: Uninitialised Arrays

A single uninitialised int prints a wrong number. An uninitialised char array can print a whole page of junk, or crash:

char name[20];
printf("Name: %s\n", name);   // prints junk until it finds a 0 byte

%s keeps printing characters until it hits a null terminator ('\0'). Your array has no terminator, so printf walks straight past the end of it and keeps going through whatever memory follows. Sometimes you get gibberish. Sometimes you get a segmentation fault.

Fix it the same way:

char name[20] = "";          // first byte is '\0', so %s prints nothing
char buffer[100] = {0};      // every byte zeroed

= {0} is the idiom worth remembering. It zeroes the entire array, not just the first element.

Why the Compiler Sometimes Warns and Sometimes Doesn’t

With warnings on, GCC and Clang usually catch this:

gcc -Wall -Wextra -o program program.c

You get:

warning: 'total' is used uninitialized [-Wuninitialized]

But the warning is not guaranteed. If the variable is passed to another function, or its use is behind a condition the compiler cannot follow, the warning disappears and the bug ships.

That is why -Wall -Wextra is a habit, not a guarantee. It catches the obvious cases. It will not catch all of them.

Finding It When the Compiler Stays Quiet

Two tools find what the compiler misses:

Valgrind (Linux, macOS) reports reads of uninitialised memory at runtime:

valgrind --track-origins=yes ./program

You get a line naming the exact variable and the line number where it was read before being written.

AddressSanitizer works on Windows too, through GCC or Clang:

gcc -fsanitize=address -g -o program program.c
./program

It is faster than Valgrind and catches out-of-bounds reads as well — which is what the uninitialised char array above actually is.

The Related Bug You Will Meet Next

Garbage values and scanf problems tend to appear in the same program, because both come from not controlling what is in memory. If your scanf is skipping input or looping forever, that is a separate cause with a separate fix:

Why your C program skips the second scanf — the leftover newline in the input buffer
Why your C program loops forever when you type a letter — scanf failing and never consuming the bad input
Why your C program crashes when you forget & in scanf — writing to an address that isn’t yours

The Rule, Stated Once

In C, a variable has a value the moment it exists — you just did not choose it.

Initialise every variable when you declare it. Use = {0} for arrays. Compile with -Wall -Wextra. Reach for Valgrind or AddressSanitizer when the compiler says nothing but the output looks wrong.

The habit costs one line per variable and removes an entire class of bug that is otherwise almost impossible to reproduce.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

scanf vs fgets in C: Which One to Use (and Why scanf Skips Input)

Yunus Emre Güzel — Tue, 27 Oct 2026 13:27:02 +0000

The short answer is: use fgets to read a line of text. Use scanf to read a single formatted value when you already know exactly what it should look like. That's the whole rule. The rest of this post explains why it holds, what breaks when you get it wrong, and how to use each one safely.

What scanf Actually Does

scanf is a formatted reader. You give it a pattern, and it tries to match the input against that pattern:

int age;
scanf("%d", &age);

It skips leading whitespace, reads digits until something else appears, and stops. It leaves everything it did not consume in the input buffer — including the newline you pressed Enter to send. That leftover is the source of almost every scanf bug you will meet.

If your program is skipping input or looping forever, that's why:

Why your C program skips the second scanf
Why your C program loops forever when you type a letter

What fgets Actually Does

fgets reads a whole line, up to a size limit, and keeps the newline:

char name[50];
fgets(name, sizeof name, stdin);

It reads at most 49 characters plus a null terminator. If the user typed fewer, the newline is included. If they typed more, the rest stays in the buffer for your next read. No pattern matching, no surprise. You get a string, and you decide what to do with it.

Side by Side: Reading a Name

The same task, both ways. Reading a name with a space in it — "Emre Guzel":

/* scanf: stops at the space */
char first[20];
scanf("%19s", first);
printf("%s\n", first); /* prints "Emre" only */

/* fgets: reads the whole line */
char full[50];
fgets(full, sizeof full, stdin);
full[strcspn(full, "\n")] = '\0'; /* strip the newline */
printf("%s\n", full); /* prints "Emre Guzel" */

Two things to notice. First, scanf("%s") cannot read a name with a space — it stops at the first whitespace. Second, fgets keeps the newline, so you strip it with strcspn. That strcspn line is the standard idiom. It finds the position of the newline and replaces it with a null terminator. If there is no newline (the line was longer than the buffer), it does nothing harmful.

The Overflow Problem

This is the reason fgets wins for text:

char name[10];
scanf("%s", name); /* user types 50 characters -> buffer overflow */

scanf("%s") has no idea how big your buffer is. It writes as many characters as the user types, straight past the end of the array. That's a buffer overflow — undefined behaviour, and in the worst case an exploitable one.

You can limit it with a field width:

scanf("%9s", name); /* at most 9 chars + null = 10 bytes */

But the width must be one less than the buffer size, and you have to remember to change it every time you change the array. Forget once and you have the bug back.

fgets takes the size as an argument, so it cannot get out of sync:

fgets(name, sizeof name, stdin); /* always correct */

sizeof name updates automatically when you resize the array. That's the whole argument.

Where scanf Is Still the Right Tool

This is not a "never use scanf" post. scanf is better when the input is genuinely structured and you want the parsing done for you:

int day, month, year;
if (scanf("%d/%d/%d", &day, &month, &year) == 3) {
    printf("Parsed: %04d-%02d-%02d\n", year, month, day);
}

Doing that with fgets means reading the line, then calling sscanf on it — which is actually the better pattern, and the next section explains why.

The Pattern That Avoids Both Problems

Read the line with fgets, then parse it with sscanf. You get fgets's safety and scanf's convenience:

char line[100];
int age;

printf("Age: ");
if (fgets(line, sizeof line, stdin) == NULL) {
    return 1; /* EOF or read error */
}
if (sscanf(line, "%d", &age) != 1) {
    printf("That is not a number.\n");
    return 1;
}
printf("You are %d\n", age);

Why this is better than scanf("%d", &age) directly:

Bad input is consumed. If the user types "abc", fgets takes the whole line, so there is nothing left to poison the next read. With scanf, "abc" stays in the buffer and every later read fails too.
You can report the error. sscanf returns how many fields it matched, so != 1 tells you the parse failed.
Nothing overflows. The line is bounded by sizeof line.

The Comparison Table

	scanf("%s")	fgets()
Reads	one word	one line
Stops at space	yes	no
Keeps newline	no	yes
Buffer safe	no (needs width)	yes (size arg)
Bad input left in buffer	yes	no
Return value	fields matched	pointer, or NULL on failure
Best for	structured input	text input

Checking the Return Value

Both functions tell you when they fail. Almost nobody checks:

if (scanf("%d", &age) != 1) {
    /* input was not a number */
}

if (fgets(line, sizeof line, stdin) == NULL) {
    /* EOF or error */
}

scanf returns the number of fields it successfully matched. fgets returns NULL on failure. Ignoring these is how programs crash on empty input.

The Rule, Stated Once

Reading text? fgets. Reading a number? fgets then sscanf. Reading a rigidly formatted string like a date? scanf is fine, but fgets + sscanf is still safer. The reason is simple: scanf leaves bad input in the buffer and cannot know your buffer size. fgets does neither. The one extra line to strip a newline is a small price for not chasing an input bug for an hour.

If you are new to reading input in C, start with the complete guide to user input in C, then come back here. And if your program is crashing rather than misbehaving, that's usually the missing &: why your C program crashes when you forget & in scanf.

Originally published on my blog.

PySerial Access Is Denied on a COM Port: Why and How to Fix It

Yunus Emre Güzel — Sun, 25 Oct 2026 02:02:10 +0000

Your Arduino is plugged in and your Python script is ready. It crashes on the first line with could not open port 'COM3': PermissionError(13, 'Access is denied.'). When PySerial says access is denied, it's almost never a real permission problem. Another program is already using the port.

The Problem: PySerial Says Access Is Denied

import serial

arduino = serial.Serial("COM3", 9600)

Two lines, and the second one fails. The port name is right and the cable is fine.

How to Read the Error Message

The full line usually looks like SerialException: could not open port 'COM3': PermissionError(13, 'Access is denied.'). Each part says something:

PermissionError(13) – error number 13 is the operating system's generic "that request is not allowed". It covers files, folders and ports alike.
could not open port 'COM3' – PySerial asked Windows to open the port and Windows said no.
Access is denied – on a serial port, this almost always means: someone else has it open.

The misleading part is the word "permission". On Linux, a serial permission error really is about user groups. On Windows it nearly always means the port is busy – and no amount of running your script as administrator will fix that, because administrators get refused too. Only one program at a time can hold a serial port.

Why It Happens

A serial port can be open in only one program at a time. Whoever opens it first keeps it, and everyone else is refused. The usual suspects, in order:

The Arduino IDE. If its Serial Monitor or Serial Plotter is open, it holds the port. Closing the monitor window is not always enough – close the whole IDE if in doubt.
An earlier run of your own script. A terminal from ten minutes ago with a script stuck in a while True: loop still owns the port. So does a Python shell (IDLE, or a python session) where you opened the port and never closed it.
Your own code opening the port twice. Two serial.Serial("COM3", 9600) calls in one script – easy to do in a loop – and the second is denied by your own first one.
Other serial software. Anything that talks to boards: Cura and other 3D-printer slicers, flashers, serial terminal apps like PuTTY.

Find What Is Holding the Port

On Windows, press Ctrl+Shift+Esc to open Task Manager, go to the Details tab, and look for every python.exe, pythonw.exe and arduino.exe (or java.exe – the Arduino IDE is Java). End the ones you are not using, then run your script again.

If that finds nothing, unplug the USB cable, count to five, and plug it back in. Unplugging force-releases the port from any program that is keeping it open without a window.

The Fix: Close Whatever Holds the Port

Close the Serial Monitor and the Serial Plotter in the Arduino IDE.
Stop any earlier run of your script. In VS Code, click the bin icon on each old terminal.
Still refused? Unplug the USB cable, wait a few seconds and plug it back in.

It works the other way round too. While your Python script holds the port, the Arduino IDE can't upload a new sketch. Stop the script first – you will see "Upload failed" or "Access is denied" in the IDE's status bar otherwise.

Close the Port in Your Own Code

Open the port with a with block, and Python closes it for you, even when the script crashes halfway:

import serial
import time

with serial.Serial("COM3", 9600, timeout=1) as arduino:
    time.sleep(2)              # the board restarts when the port opens
    arduino.write(b"R")
    reply = arduino.readline().decode().strip()
    print(reply)

The time.sleep(2) matters. Most Arduino boards, the Uno included, restart when a program opens the serial port. Send data in the first second or two and the board misses it, because it's still starting up.

The timeout=1 matters just as much. Without it, readline() waits forever if the board never sends a newline, and your script hangs – looking, from the outside, a lot like the port problem returning. With a timeout, readline() returns whatever arrived (an empty bytes object if nothing did) after one second, and your script keeps running.

If you prefer opening the port the plain way, close it on every path – including the error path:

arduino = serial.Serial("COM3", 9600, timeout=1)
try:
    arduino.write(b"R")
finally:
    arduino.close()

Wrong Port Name: A Different Error

If the port doesn't exist, the message changes to FileNotFoundError. List the ports your PC can see with:

python -m serial.tools.list_ports

The number often changes when you use a different USB socket, so COM3 yesterday can be COM5 today. Watch the output while you unplug and replug the board – the port that appears and disappears is yours. A few laptops also ship Bluetooth serial ports (often the lowest COM numbers), and picking one of those by mistake gives you either this same access-denied error or connection after which nothing arrives.

Can Two Programs Share the Port?

Not natively – the one-program rule is built into the operating system's serial driver, on Windows and Linux alike. Tools exist that create virtual port pairs and split the data, but for Arduino work the honest answer is simpler: read the reply in the same program that opens the port, and close it when you are done. If you need the Serial Monitor and your script at the same time, make your script print what it receives, and close the IDE.

Still Denied? The Last Three Causes

If Task Manager is empty, the cable is out and back in, and the error still shows, work down this list:

The USB controller is stuck. In Device Manager, find "Ports (COM & LPT)", right-click your board's entry, choose Uninstall device, then unplug and replug. Windows rebuilds the port from scratch.
A driver took the port hostage. Some antivirus and "device control" tools block raw serial access. If your company laptop denies every port including ones with nothing plugged in, that is what is happening – it is an IT policy, not PySerial.
A clone board with broken USB drivers. Unos use ATmega16U2 for USB (built into Windows), but many clones use a CH340 chip that needs its own driver. The giveaway: the board appears in Device Manager with a yellow warning icon. Install the CH340 driver and both the warning and the strangeness go away.

Which Error Means What

All three PySerial opening errors sound alike the first week. The fast way to tell them apart:

PermissionError(13) / Access is denied – the port exists but someone else has it open. Close the holder.
FileNotFoundError(2) / No such file or directory – the port name is wrong or the board is unplugged. Run the list_ports command.
SerialException: Port is already open – your own Python object opened the port twice. Reuse the object or close it first.

PySerial Access Is Denied on Linux

On Linux the error reads Permission denied: '/dev/ttyACM0', and there it really is about permissions. Add your user to the group that owns serial ports, then log out and back in:

sudo usermod -a -G dialout $USER

On Windows, though, a PySerial access is denied error means the port is busy. The PySerial short introduction shows more ways to open and read a port.

To see serial used in a full project, read AI agents with hardware integration. And if your board stops answering while it blinks, the cause is probably delay() freezing your Arduino.

What was holding your port: the Serial Monitor or an old script? Tell me in the comments.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

Free Audiobook Creator: How I Built a Tool That Reads Any Public-Domain Book Aloud

Yunus Emre Güzel — Sun, 25 Oct 2026 01:39:00 +0000

You click a book. Two seconds later a voice starts reading it to you — page one, chapter one, start to finish. No signup, no payment, no download. I built that this month, and this post is the engineering story: where the books come from, why the first version read the wrong ones, and the three bugs that made it lie to people.

Where the books actually come from

The app searches two free sources in order. First Project Gutenberg (via the Gutendex API) — real, complete, proofread public-domain books. If nothing matches, it falls back to OpenLibrary’s full-text scan archive (the Internet Archive’s scanned copies). All public domain, all free, all legal.

That means classics: Frankenstein, Dracula, Alice in Wonderland, War and Peace. It does not mean Percy Jackson or Harry Potter — those are copyrighted, no free copy exists anywhere, and no honest program can read them. More on that in a second, because it broke my search results badly.

Bug 1: the search that returned 12 lies

My first version worked like this: query the APIs, take the first 12 results, show them. For famous books, fine. Then I searched “long way down” and got back 12 completely unrelated titles — books that merely had the word “down” somewhere. The API (OpenLibrary) returns loosely-related matches when strict matches are missing, and my code just… displayed whatever came back.

The fix was scoring: every result gets a match score computed from how many of the query’s words appear in the title and author, and anything scoring zero gets thrown out. “Long way down” now returns exactly one book — the only thing the free archives actually have for that title — instead of a page of junk.

Bug 2: the book that wasn’t a book

Next fun failure: for that same query, the only full-text “scan” the Internet Archive had was a 2,498-character poem — “It’s a Long Way Down to the Soup Line” by Joe Hill (the labor organizer, not the horror writer). My reader happily narrated all 38 sentences like it was a novel, then stopped.

Now the app measures what it downloaded before it starts. Under 5,000 characters means it’s a poem or a pamphlet, not a book — so it tells you that in plain words and auto-tries the next edition instead of a silent stop. If the short piece is genuinely all that exists, it says exactly that. A program that can’t be honest about limits isn’t smart, it’s just confident.

Bug 3: half of War and Peace

The worst one was invisible. My reader had a length cap — 900,000 characters, silently truncating anything longer. You never got an error. You just listened to half of War and Peace and the ending never came. Doubling the cap and surfacing the numbers (“reading all 315,342 words, ~590 pages”) fixed it: the app states what it’s reading and how long it is.

The audio: human narrators first, machine second

For classics there’s a treat: LibriVox volunteers have already recorded most of them, and those human-narrated audiobooks live on the Internet Archive. The app finds those first — real human voices, chapter by chapter, with auto-advance.

Here’s where I learned that “official APIs die silently.” LibriVox’s search API started returning 404 for every single title — not rate limiting, just dead. Everything that used it fell back to a slow AI-planner path that took ten seconds of nothing before reading started. The fix: search the archive.org librivoxaudio collection directly, rank by exact title match, and keep the slow planner only as a last resort. A click now starts narration in about two seconds.

When no human recording exists, a machine voice reads the text — chunked into parts, with the next part synthesized in the background while the current one plays, so a whole novel reads cover to finish without gaps.

What I’d tell anyone building this

Never display API results unfiltered — score them or you’re shipping someone else’s garbage.
Measure the artifact before you serve it. Size, word count, anything. Silent truncation is a bug your users will never report, because they’ll never know.
Assume every third-party API will die. Have the fallback built before the funeral.
Tell the truth in your UI. “The archives only have this short piece” beats a confident wrong answer every time.

Try it free at emreguzel.ca — search a classic, click, listen. And if you’re building something similar, I’d genuinely like to hear how you handled the thin-scan problem; leave a comment.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

I built an AI voice chat app with custom characters — here's the stack and everything that broke

Yunus Emre Güzel — Sun, 18 Oct 2026 01:54:50 +0000

I got tired of chatbots that can only talk. I wanted one that sounds like the character, keeps its personality over a whole conversation, and answers me in my own language.

So I built IboChat: a Flask app where every character replies in text and out loud, in 24+ languages, and where you can create your own character in a couple of minutes. It's live at chat.emreguzel.ca — everything below is the real story of how it's built and what went wrong along the way.

The shape of the thing

The stack is boring on purpose:

Flask, one file, serving pages + JSON API + audio endpoints
GLM (glm-4.5-air) through the Z.ai API as the brain
faster-whisper running locally for speech-to-text
SQLite + Werkzeug hashing for accounts, auto-created on startup
Docker behind Cloudflare

No React, no build step, no microservices. The interesting parts are the voice pipeline and the character system.

How a message travels

You type or talk. If you talk, faster-whisper turns it into text on the server CPU. The backend then builds the prompt the same way every single time: the character's personality prompt, a window of recent history, your language code. The model never sees a naked message — that discipline is what keeps a character from drifting into generic-assistant mush halfway through a chat.

The reply comes back in character, then the fun part starts: making it speak.

The voice pipeline: three tiers because no engine does it all

This is where most of my hair loss happened. I needed "sounds like the character" AND "works in any language" AND "doesn't fall over". One engine couldn't do all three, so /speak tries three paths in order:

GPT-SoVITS — best cloned voices, ~5–18 seconds to synth, but English/Chinese/Japanese/Korean only, and it permanently eats ~3.9GB of VRAM once loaded.
OmniVoice Studio — any language, ~30–40s, through an OpenAI-compatible endpoint.
Edge TTS — Microsoft's free neural voices. Nothing cloned, but 24 languages, zero latency, never fails.

The last one is the safety net that means the app always has something to say.

The bug that took me three days: one GPU, two voice models

GPT-SoVITS and OmniVoice both live on the same 4GB GPU. For a while, loading one starved the other and audio came out corrupted — I genuinely thought I had a bad CUDA install and reinstalled PyTorch twice. The actual fix was orchestration, not hardware:

Flask launches GPT-SoVITS on demand, never at boot
A watchdog thread kills it after 120 idle seconds
OmniVoice's VRAM gets flushed before every call so the two models stop wrestling

Cold starts, or the silence of death

The voice model takes ~30–50 seconds to load. If a user sends a message during that window, the request just... hangs. My first version held the request open. Now the server probes whether the model is ready, and if not it falls through to the next voice tier instead of making a human wait in silence. Users hear a slightly less fancy voice; they don't hear a timeout.

The small fights

Rate limits. The AI endpoint rate-limits under load. Retries with exponential backoff — a chatty user sees a pause, never an error.
Mobile autoplay. Browsers refuse to auto-play audio before the user has touched the page. First reply plays after the first tap. Annoying, unfixable, fine.
Voice cloning from YouTube. Cloning a character voice is automated now: yt-dlp grabs a clean clip, ffmpeg trims it, OmniVoice builds the profile. Cached per character so it only happens once. Getting clips that were clean enough was its own evening of pain.
The endpoint is called /api/gemini. Early version used Google Gemini. It proxies to Z.ai now. I left the name because renaming would break my own frontend and, honestly, it's a nice little tombstone of the architecture's history.

Cost

One thing I'll say for anyone budgeting this: with a cheap model (glm-4.5-air class) and a text-only reply per message, the LLM side of a conversation costs a rounding error. Voice is free (edge-tts) or electricity (the two GPU models).

Try it / what's next

It's live: chat.emreguzel.ca. Characters are clearly labeled as AI parodies.

Next up: giving characters long-term memory between sessions, and better mid-conversation language switching.

If you build something with voice + AI, drop a link in the comments — I want to see how other people solve the one-GPU-two-models problem.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

Why Your C Program Crashes When You Forget & in scanf (and How to Fix It)

Yunus Emre Güzel — Thu, 15 Oct 2026 00:52:23 +0000

You write your first C program, run it, and the terminal window closes instantly. Or worse, it prints a random huge number and then crashes. You check the code three times and every line looks right—except one tiny character. Forgetting the & in scanf() is one of the most common mistakes beginners make in C, and it causes problems that look much bigger than they are.

The Problem: scanf Without the Ampersand

Here is a small program that asks for an age and prints it back:

#include <stdio.h>

int main(void) {
    int age;
    printf("Enter your age: ");
    scanf("%d", age);   /* missing & */
    printf("You are %d years old.\n", age);
    return 0;
}

On some computers this crashes right away. On others it stores the number in a random memory location and prints garbage, or it seems to work once and then fail later. The line scanf("%d", age); looks almost identical to the correct version, so the bug is easy to miss.

Why It Happens

scanf() needs to know where to put the value it reads. It needs the memory address of the variable, not the variable’s current value. The & operator gives that address. When you write &age, you are saying “store the input here.”

When you forget & and write scanf("%d", age);, scanf() treats whatever number is already inside age as a memory address. That address is probably not valid, so the program writes to memory it does not own. That is undefined behavior: the compiler is allowed to crash, print nonsense, or appear to work.

The Fix: Add the Ampersand

Change the scanf() call so it passes the address of age:

#include <stdio.h>

int main(void) {
    int age;
    printf("Enter your age: ");
    scanf("%d", &age);   /* correct */
    printf("You are %d years old.\n", age);
    return 0;
}

Now scanf() knows exactly where age lives in memory, and the input is stored safely. The rule is simple: for int, float, double, char, and other single variables, always use & with scanf().

When You Do NOT Need the Ampersand

Strings and arrays are already memory addresses in C. When you read a string with scanf("%s", name) or a whole line with fgets(name, sizeof name, stdin), you write the variable name without &:

#include <stdio.h>

int main(void) {
    char name[50];
    printf("Enter your name: ");
    scanf("%s", name);   /* no & needed for arrays */
    printf("Hello, %s!\n", name);
    return 0;
}

The easy way to remember: scanf() needs an address. Single variables need & to produce one; arrays already are one.

Try It Yourself

Run this program first without the & on line 9, then with it. Notice the difference:

#include <stdio.h>

int main(void) {
    int length;
    int width;

    printf("Enter length: ");
    scanf("%d", &length);
    printf("Enter width: ");
    scanf("%d", &width);

    printf("Area = %d\n", length * width);
    return 0;
}

For the full picture on reading numbers, strings, and validating input safely, read my complete guide to user input in C. If you are just starting out, begin with the introduction to C programming.

Have you ever forgotten the & in scanf()? Tell me what happened in the comments and I’ll help you figure it out.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

More from my lab: IboChat — talk to AI characters by voice in 24+ languages (AI parodies, not real people) — and free web tools on emreguzel.ca. Tutorials like this one are published first on my Coding Blog.

Why delay() Freezes Your Arduino and How to Use millis() Instead

Yunus Emre Güzel — Wed, 14 Oct 2026 13:38:14 +0000

For my AI agent project, I wanted an Arduino to show what the AI was doing: a blue LED pulses while it researches, a yellow LED pulses while it debates, and a servo sweeps back and forth while it’s busy. The Python program sends one letter over USB whenever the state changes. The first version you’d naturally write uses delay(), and it has a frustrating bug: the Arduino ignores new messages for seconds at a time. Here’s why, and how millis() fixes it.

The Problem: The Arduino Stops Listening

Here’s the obvious way to blink an LED and sweep a servo:

void loop() {
  if (Serial.available() > 0) {
    state = Serial.read();
  }

  if (state == 'B') {
    digitalWrite(BLUE_LED, HIGH);
    delay(500);
    digitalWrite(BLUE_LED, LOW);
    delay(500);
    for (int angle = 0; angle <= 180; angle++) {
      servo.write(angle);
      delay(15);
    }
  }
}

It looks right, but one pass through loop() now takes almost four seconds: one second for the LED and about 2.7 seconds for the sweep. During all that time the Arduino only checks for new messages once. When the AI finishes and Python sends W, the board keeps blinking blue for a few more seconds, and the LED and servo can’t move at the same time either.

Why delay() Causes It

delay(500) doesn’t mean “wait here while doing other things”. It means “do nothing at all for 500 milliseconds”. The Arduino can’t read serial, update the servo, or blink another LED while it’s inside delay(). Every delay you add makes the whole board slower to react.

The Fix: Check the Clock with millis()

millis() returns how many milliseconds have passed since the board started. Instead of stopping to wait, each part of the program remembers when it last did something, and on every pass through loop() it checks: “has enough time passed yet?” If not, it moves on straight away. loop() then runs thousands of times a second, so everything stays responsive.

#include <Servo.h>

const int BLUE_LED = 12;
const int YELLOW_LED = 13;
const int SERVO_PIN = 8;

Servo servo;
char state = '0';
unsigned long lastLedToggle = 0;
unsigned long lastServoStep = 0;
bool pulseOn = false;
int angle = 90;
int step = 2;

// Blink one LED without stopping the program
void pulse(int pin, unsigned long intervalMs) {
  unsigned long now = millis();
  if (now - lastLedToggle >= intervalMs) {
    pulseOn = !pulseOn;
    lastLedToggle = now;
  }
  digitalWrite(pin, pulseOn ? HIGH : LOW);
}

// Move the servo a little, only when it's time to
void sweep(unsigned long intervalMs) {
  unsigned long now = millis();
  if (now - lastServoStep >= intervalMs) {
    lastServoStep = now;
    angle += step;
    if (angle >= 180 || angle <= 0) {
      step = -step;  // turn around at the ends
    }
    servo.write(angle);
  }
}

void setup() {
  Serial.begin(9600);
  pinMode(BLUE_LED, OUTPUT);
  pinMode(YELLOW_LED, OUTPUT);
  servo.attach(SERVO_PIN);
  servo.write(90);
}

void loop() {
  if (Serial.available() > 0) {
    state = Serial.read();
    digitalWrite(BLUE_LED, LOW);
    digitalWrite(YELLOW_LED, LOW);
  }

  if (state == 'B') {         // researching
    pulse(BLUE_LED, 500);
    sweep(15);
  } else if (state == 'Y') {  // debating: faster pulse
    pulse(YELLOW_LED, 200);
    sweep(15);
  } else {                    // '0' idle or 'W' done
    servo.write(90);
  }
}

Now a new letter takes effect within a few milliseconds, and the LED pulses while the servo sweeps. Writing now - lastLedToggle >= intervalMs (instead of comparing against a future time) also keeps working when millis() wraps back to zero after about 49 days.

Two More Gotchas from This Project

The board resets when Python connects. Opening the serial port restarts an Arduino Uno, so the first letters you send get lost. Wait about two seconds after serial.Serial(...) before sending anything: time.sleep(2).
Install pyserial, not serial. pip install serial installs a different package. If Python says module 'serial' has no attribute 'Serial', run pip uninstall serial pyserial and then pip install pyserial.

A small SG90 servo is fine on the Uno’s 5V pin, but a bigger servo can pull so much power that the board resets mid-sweep. Give it its own 5V supply and connect the grounds together.

See It in the Full Project

The Python side, the wiring steps and how the AI agents decide which letter to send are all in Architecting Autonomous AI Agents with Hardware Integration. If you’re new to agents, start with Creating Agents: A Complete Guide.

What are you building with your Arduino? Tell me in the comments, and I might write a tutorial for it.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

Why Your C Program Loops Forever When You Type a Letter

Yunus Emre Güzel — Wed, 14 Oct 2026 13:34:17 +0000

You write a C program that asks for a number. You test it, type abc by accident, and the program goes crazy: it prints the same question again and again, forever, and you have to close the terminal. This is one of the first real bugs most people hit in C. The good news is that the cause is simple and the fix is about five lines.

The Problem: scanf Loops Forever

Here is a typical program that keeps asking until it gets a valid age:

#include <stdio.h>

int main(void) {
    int age = -1;
    while (age < 0) {
        printf("Enter your age: ");
        scanf("%d", &age);
    }
    printf("You are %d years old.\n", age);
    return 0;
}

Type 20 and it works. Type abc and “Enter your age:” fills the screen.

Why It Happens

When you type something and press Enter, it goes into the input buffer, a waiting area that scanf reads from. scanf("%d", ...) looks at the start of the buffer and tries to read a number.

If it finds abc, it can’t turn that into a number, so it gives up. But it doesn’t remove abc from the buffer. The loop runs again, scanf looks at the buffer, finds the same abc, fails again, and so on forever. It never waits for you to type, because there’s still something in the buffer.

Your program also has no idea it failed, because it never asked. scanf tells you how many values it read successfully through its return value, and the code above ignores it.

The Fix: Check the Return Value and Clear the Bad Input

Two changes fix it. First, check that scanf returned 1 (one number read). Second, when it didn’t, throw away everything up to the end of the line so the next try starts clean:

#include <stdio.h>

int main(void) {
    int age;
    printf("Enter your age: ");

    while (scanf("%d", &age) != 1) {
        int c;
        while ((c = getchar()) != '\n' && c != EOF) {
            /* throw away the bad input */
        }
        if (c == EOF) {
            return 1;  /* input closed, nothing more to read */
        }
        printf("That's not a number. Try again: ");
    }

    printf("You are %d years old.\n", age);
    return 0;
}

The inner while loop reads one character at a time with getchar() until it reaches the newline from the Enter key. That empties the buffer, so the next scanf waits for new input. The EOF check stops the program cleanly if the input ends, for example when someone presses Ctrl+Z on Windows or Ctrl+D on Linux and Mac.

Other Input Traps in C

While you’re fixing input, watch for these too:

Forgetting the &: scanf("%d", age) passes the value instead of the address, which usually crashes the program. It needs &age.
Names with spaces: scanf("%s", name) stops at the first space, so “Emre Guzel” becomes “Emre”. Use fgets(name, sizeof name, stdin) instead. It reads the whole line and can’t overflow the array.
fgets keeps the newline: remove it with name[strcspn(name, "\n")] = '\0'; (include <string.h>).
Never use gets(): it has no length limit and was removed from C in C11.

Try It Yourself

Run both versions and type abc, then 12abc. The second one is interesting: scanf reads 12 and leaves abc behind, so a later scanf in your program would fail. If that matters, read the whole line with fgets and convert it with strtol, which tells you exactly where the number ended.

For the full picture, with practice programs for the area of a rectangle and a circle and using input with if and else, read my complete guide to user input in C. If you’re just starting out, begin with the introduction to C programming.

Have you hit this infinite-loop bug before? Tell me what you typed in the comments, and I’ll help you fix it.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

Why Your Tkinter App Freezes (Not Responding) and How to Fix It

Yunus Emre Güzel — Wed, 14 Oct 2026 13:33:21 +0000

You build a Tkinter app that fetches the weather, asks an AI model a question, or downloads a file. You click the button and the whole window freezes. You can’t drag it, the button stays pressed, and Windows adds “(Not Responding)” to the title. A few seconds later it suddenly comes back with the answer. It shows up in exactly the kind of apps from my Tkinter guide, like the weather app and the AI image app, and the fix is the same every time.

The Problem: The Window Freezes While It Works

Here is a small app that shows the problem. time.sleep(3) stands in for any slow job, like an API call:

import time
import tkinter as tk

def on_click():
    label.config(text="Loading...")
    time.sleep(3)  # pretend this is an API call
    label.config(text="Done!")

window = tk.Tk()
label = tk.Label(window, text="Click the button", font=("Arial", 14))
label.pack(padx=20, pady=10)
tk.Button(window, text="Start", command=on_click).pack(pady=10)
window.mainloop()

Click Start and the window locks up for three seconds. You never even see “Loading…”.

Why Tkinter Freezes

Everything in a Tkinter app runs on one main thread. window.mainloop() is a loop that keeps redrawing the window and handling clicks. When you click the button, mainloop() calls your function and waits for it to finish.

While your function sits in time.sleep() or waits for a server, mainloop() can’t do anything else. No redraws, no clicks, no “Loading…” text. That’s also why the label change never shows: Tkinter only redraws once your function returns.

The Fix: Run Slow Work in a Thread

Move the slow part into a background thread, so the main thread is free to keep the window alive. When the work is done, hand the result back to the main thread with window.after():

import threading
import time
import tkinter as tk

def slow_task():
    time.sleep(3)  # the API call goes here
    window.after(0, show_result, "Done!")  # back to the main thread

def show_result(text):
    label.config(text=text)
    button.config(state="normal")

def on_click():
    button.config(state="disabled")
    label.config(text="Loading...")
    threading.Thread(target=slow_task, daemon=True).start()

window = tk.Tk()
label = tk.Label(window, text="Click the button", font=("Arial", 14))
label.pack(padx=20, pady=10)
button = tk.Button(window, text="Start", command=on_click)
button.pack(pady=10)
window.mainloop()

Now “Loading…” appears straight away, and you can drag the window around while the task runs.

What each part does

threading.Thread(target=slow_task, daemon=True).start() runs slow_task at the same time as the window. daemon=True means the thread won’t keep Python running after you close the window.
window.after(0, show_result, "Done!") asks the main thread to run show_result("Done!") as soon as it can.
Disabling the button stops people from clicking Start ten times and starting ten threads.

The One Rule: Only the Main Thread Touches Widgets

It’s tempting to write label.config(text="Done!") directly inside slow_task. Sometimes that even seems to work. But Tkinter isn’t thread-safe, so changing widgets from another thread can cause random errors and crashes that are very hard to track down. Always go through window.after().

The same pattern works for any slow job: requests.get() for an API, a call to an AI model, reading a big file, or processing an image with Pillow.

Where to Go Next

My Tkinter in Python guide goes from a first window to full projects, including the weather and AI apps where this fix matters most. If you’re still getting used to Python itself, start with Python for beginners.

Did your Tkinter app freeze on something else? Paste the error in the comments, and I’ll take a look.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

Introduction to C programming

Yunus Emre Güzel — Wed, 14 Oct 2026 13:32:30 +0000

C programming is one of the best places to start learning how computers really work. It’s fast, it’s everywhere, and almost every modern language borrows from it. This introduction to C programming covers where C came from, why it still matters, and how to write your first programs with text, numbers and variables.

A Short History of C Programming

C was created by Dennis Ritchie at Bell Labs in the early 1970s. He needed a better language to rewrite the Unix operating system. Before C, programmers wrote systems in assembly language, which was hard to read and only worked on one type of machine.

C changed that, because it offered readable code while still giving full control over the hardware. Unix was rewritten in C, so it could move to new computers easily. By the 1980s, C had become the standard language for serious software.

Why We Still Use C

The main reason is speed. C compiles straight into machine code, so it doesn’t need a heavy runtime or virtual machine. It also gives you direct access to memory, so you can manage hardware precisely. And it’s portable: code written on Windows usually runs on Linux with very few changes.

That’s why C sits at the core of Windows, Linux and macOS. It also runs embedded devices such as smartwatches, routers and car computers, where memory is tight and speed matters.

C is also called the mother of modern languages. C++, C# and Objective-C grew directly out of it, while Java, JavaScript and PHP copy much of its syntax. So when you learn C, the basic shape of most other languages starts to look familiar.

Set Up VS Code for C Programming

To write C in VS Code, you need a C compiler such as GCC installed on your computer. Then install the Run GCC extension by MushroomFX. It lets you compile and run a C file with one click, instead of typing commands in the terminal.

With the extension installed, open a file such as main.c with this code and click the Play button:

#include <stdio.h>

int main(){
    printf("Hello, World!\n");
    return 0;
}

Your First C Program: Hello World

Printing “Hello, World!” is the traditional first program in any language. It’s short, but it checks that your compiler works and shows the basic structure every C program needs:

#include <stdio.h> loads the standard input/output library, which provides printf.
int main() is where every C program starts. The operating system looks for it first.
printf("Hello, World!\n"); prints the text. \n moves to a new line, and the semicolon ends the statement.
return 0; ends the program and tells the system that everything went well.

#include <stdio.h>

int main(){
    printf("Hello, World!\n");
    return 0;
}

Compile and run from the terminal

If you prefer the terminal, you can also compile the file yourself:

gcc .\main.c -o main.exe

gcc is the GNU Compiler Collection, which turns C code into machine code.
.\main.c is your source file in the current folder.
-o main.exe sets the name of the program it creates.

Then run the program:

./main.exe

The ./ tells the terminal to look in the current folder. Terminals ask for this on purpose, so they never run a program with the same name from somewhere else by mistake.

Print more than one line

To print more, add more printf lines. Each one ends with \n, so the next line starts underneath:

#include <stdio.h>

int main(){
    printf( "Emre Guzel\n");
    printf("Favorite place in the world?\n");
    printf("Istanbul\n");
    return 0;
}

You can also print an empty line with printf("\n");, which makes the output easier to read:

#include <stdio.h>

int main(){
    printf( "Favorite car? \n");
    printf("Mercedes Maybach S class s 500 \n");
    printf("\n");
    printf("Favorite Resturan\n");
    printf("Nusret\n");
    printf("\n");
    printf("Favorite food\n");
    printf("Adana Kebab \n");
    return 0;
}

Doing Maths in C Programming

C can calculate too. Here printf works out 1 + 1 and prints the answer:

#include <stdio.h>

int main(){
    printf( "1 + 1 = %d\n", 1 + 1 );
    return 0;
}

%d is a placeholder for a whole number. When the program runs, C works out 1 + 1 and puts the result where %d is:

Multiplication uses *:

#include <stdio.h>

int main(){
    printf( "100 X 100 = %d\n", 100 * 100 );
    return 0;
}

Division uses /:

#include <stdio.h>

int main(){
    printf( "500 / 5 = %d\n", 500 / 5 );
    return 0;
}

Variables and Whole Numbers (int)

A variable is a named box in memory that holds a value. Instead of remembering a memory address, you use the name. For example, a game might keep the score in a variable called playerScore and update it every time you earn points.

An int holds a whole number, such as 42, -100 or 0. It can’t hold 3.14, because that needs a decimal type. On most computers an int uses 32 bits, so it fits numbers from about -2.1 billion to 2.1 billion.

Here two int variables are added together:

#include <stdio.h>
int main(){
    int num1 = 100;
    int num2 = 200;
    printf("100 + 200 is equal to : %d\n", num1 + num2);
}

The same works for division. Note that dividing two ints gives a whole number, so 7 / 2 would give 3:

#include <stdio.h>
int main(){
    int num1 = 500;
    int num2 = 2;
    int result = num1 / num2;
    printf("500 / 2 is equal to : %d\n", result);
}

Practice: area of a rectangle

The area of a rectangle is length × width. With variables, the formula reads almost like maths:

#include <stdio.h>
//Area of rectangle
//a= lw
int main(){
    int length = 5;
    int width = 4;
    int result = length * width;
    printf("Area of the rectangle is: %d %s\n", result, "mm²");
}

Decimal Numbers (float)

A float holds a number with a decimal point, such as 3.14, -0.001 or 0.5. Use int when you count things, like 5 apples. Use float when you measure them, like 1.75 metres or $9.99.

The name comes from how computers store these numbers: the decimal point can “float”, a bit like scientific notation. That’s how a float can hold both very large and very small values.

#include <stdio.h>
int main(){
    float num1 = 9.9;
    float num2 = 10.4;
    float result = num1 + num2;
    printf("9.9 + 10.4 is equal to: %.2f\n", result);
    return 0;
}

%.2f prints a float with exactly two decimals, so the sum shows as 20.30:

Practice: circumference of a circle

The circumference is 2πr. Since 2π never changes, the code stores it as a constant:

#include <stdio.h>
// Circumference of circle 
//C= 2πr 
int main(){
    const float TAU = 6.28; //3.14 * 2 = 6.28
    float radius = 65.78;
    float Circumference = radius * TAU;
    printf("Circumference of the circle is: %.3f\n", Circumference);
    return 0;
}

const stops any other part of the program from changing the value, and the capital letters tell other programmers it’s a constant. Then %.3f prints the result with three decimals:

Practice: area of a triangle

The area of a triangle is base × height ÷ 2:

#include <stdio.h>
// Area of triangle  
// A = 1/2 * b * h 
int main(){
    float base = 140.3;
    float height = 9.9;
    float result =  base * height / 2;
    printf("Area of the triangle is: %.2f\n", result);
    return 0;
}

Text in C Programming: Strings

A string is text, wrapped in double quotes. C has no separate string type. Instead, a string is an array of characters that ends with a hidden null character, \0, which marks where the text stops.

Strings are how programs talk to people. If you store 42 as an int, you can add to it. If you store “42” as a string, it’s just text to display, like the word “apple”.


#include <stdio.h>
int main(){
    char name[] = "Emre Guzel";
    char favorite_place[] = "Istanbul";
    printf("My name is: %s\n", name);
    printf("My favorite place in the world is: %s\n", favorite_place);
    return 0;
}

char name[] = "Emre Guzel"; creates a character array. The empty brackets let C work out the size, including the hidden null character.
%s is the placeholder for a string, so printf puts the name into the sentence.

Once you know the pattern, you can store as many details as you like:

// about me program with variables 
#include <stdio.h>
int main(){
    char name[] = "Emre Guzel";
    char place[] = "Dubai";
    char favoriteRestaurant[] = "Aga Baba";
    char favoriteFood[] = "Roasted lamb";
    char favoriteCar[] = "Mercedes Maybach S class s 500";
    char favoriteCodingLanguage[] = "Python";
    printf("My name is: %s\n", name);
    printf("My favorite place in the world is: %s\n", place);
    printf("My favorite restaurant is: %s\n", favoriteRestaurant);
    printf("My favorite food is: %s\n", favoriteFood);
    printf("My favorite car is: %s\n", favoriteCar);
    printf("My favorite coding language is: %s\n", favoriteCodingLanguage);
    return 0;
}

A long string can even be split across two lines. C joins the two parts into one string automatically:


// Creating the question about favorite subjects, hobbies, video games, and cars
#include <stdio.h>
int main(){
    char favoriteSubjects[] = "Math, Coding";
    char favoriteHobby[] = "Coding, AI development, and hardware development with AI; finally, I like to play chess";
    char favoriteVideoGame[] = "GTA 5";
    char favoriteCar[] = "Mercedes Maybach S class S 500, and Mercedes G Wagon 4x4, "
                          "Rolls Royce Phantom, and BMW 7 series";
    printf("My favorite subject is: %s\n", favoriteSubjects);
    printf("My favorite hobby is: %s\n", favoriteHobby);
    printf("My favorite video game is: %s\n", favoriteVideoGame);
    printf("My favorite car is: %s\n", favoriteCar);
    return 0;
}

Project: Combine Strings, ints and floats

Now let’s mix all three types in one program:

// About me program
#include <stdio.h>
int main(){
    char Name[] = "Alexhander";
    int age = 25;
    float monthsOld = 25 * 12;
    printf("My name is: %s\n", Name);
    printf("I am %d years old.\n", age);
    printf("I am %.1f months old.\n", monthsOld);
    return 0;
}

%s prints the name, %d prints the age and %.1f prints the months with one decimal.
Because monthsOld is a float, the program prints 300.0 rather than 300.

Constants and bigger numbers

This version stores everything as constants and adds two bigger number types:

// Succes and about me program
#include <stdio.h>

int main() {
    // Personal preferences
    const char FAVORITE_CAR[] = "Rolls Royce Cullinan";
    const char FAVORITE_FOOD[] = "Shawarma";
    const int FAVORITE_NUMBER = 9;

    // Performance and financial metrics
    const float SUCCESS_RATE = 99.9f;
    const long long COMPANY_NET_WORTH = 10000000000000000LL;
    const double PERSONAL_NET_WORTH = 999999999.999;

    // Displaying the data
    printf("My favorite car is: %s\n", FAVORITE_CAR);
    printf("My favorite food is: %s\n", FAVORITE_FOOD);
    printf("My favorite number is: %d\n", FAVORITE_NUMBER);

    // Output formatting includes relevant symbols (%, $) for readability
    printf("My success rate is: %.1f%%\n", SUCCESS_RATE);
    printf("My company's net worth is: $%lld\n", COMPANY_NET_WORTH);
    printf("My net worth is: $%.2f\n", PERSONAL_NET_WORTH);

    return 0;
}

Every variable uses const, so none of them can change by accident. Constant names are written in UPPER_SNAKE_CASE by convention.
The f in 99.9f marks a float, while LL marks a long long, which holds numbers far bigger than an int.
A double is like a float with more precision, so it can store a long number without rounding it.
%lld prints a long long, and %% prints a real percent sign.

Practice: job title and salary

// Job title and salary program
#include <stdio.h>
int main() {
    const char JOB_TITLE[] = "Software Engineer";
    const char COMPANY_NAME[] = "OpenAI";
    const float SALARY = 2500000.00;

    printf("My job title is: %s\n", JOB_TITLE);
    printf("I work at: %s\n", COMPANY_NAME);
    printf("My annual salary is: $%.2f\n", SALARY);

    return 0;
}

The salary uses %.2f, so it prints with cents. Strictly speaking, 2500000.00 is a double in C, so writing 2500000.00f would avoid a conversion warning on some compilers.

Next Steps in C Programming

You’ve now written C programs that print text, do maths and store ints, floats and strings. The next step is to let your programs react to the person using them.

Next up: User Input in C: A Complete Guide for Beginners, where your programs start reading what the user types. For a full reference of the standard library, see cppreference.

What was the first C program you got running? Tell me in the comments, or ask if you got stuck.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

Architecting Autonomous AI Agents with Hardware Integration

Yunus Emre Güzel — Wed, 14 Oct 2026 13:32:08 +0000

Most AI agents live entirely on a screen. In this project, they reach into the real world: when the agents research, a blue LED pulses and a servo sweeps, and when they debate, a yellow LED takes over. You’ll build two projects that connect AI agents with Arduino hardware: J.A.R.V.I.S., a voice assistant with a physical status display, and an AI Pomodoro timer that fetches a research briefing during your break.

Get the code: the full source for both projects is on GitHub: J.A.R.V.I.S. and AI Pomodoro timer.

Common problem: Arduino ignoring new commands while it blinks or sweeps? See why delay() freezes your Arduino and how to use millis() instead.

The Hardware Basics

What is an Arduino?

An Arduino is a tiny programmable board that links software to the physical world. Unlike a PC, it doesn’t run an operating system. Instead, you write code on your computer, upload it over USB, and the board runs that code in a loop.

It takes inputs, such as a button press, a temperature change or a message from your computer, and turns them into outputs, such as a light, a motor or a message back. Because it’s open source and cheap, it’s the standard choice for prototypes. In this project, it’s the link that lets AI code move real parts.

What is a breadboard?

A breadboard is a plastic block full of small holes. You push wires and parts into the holes to connect them, so there’s no soldering and nothing is permanent.

Under the surface, metal strips join the holes. In the middle, each short column of five holes is connected. The long rows along the edges, marked red and blue, carry power and ground across the board. So when you wire something backwards, you just pull the wire out and move it.

What is an LED?

LED stands for Light Emitting Diode. It’s a small, efficient part that glows when current flows through it, and it stays cool and lasts for years.

Because it’s a diode, current only flows one way. So the longer leg (the anode) goes to positive, and the shorter leg (the cathode) goes to ground. LEDs are the simplest way to see what your code is doing, which is exactly how this project uses them.

Project 1: J.A.R.V.I.S., AI Agents with Arduino Status Lights

📦 Full project code: Jarvis-Hardware-Program on GitHub

J.A.R.V.I.S. is a local AI assistant with a web dashboard. A local model on Ollama writes the replies, OmniVoice Studio speaks them, and an Arduino shows what the AI is doing: blue for researching, yellow for debating, and a sweeping servo while it works.

Step 1: Wire the parts

You’ll need an Arduino Uno, a breadboard, a USB cable, a blue and a yellow LED, two 220–330Ω resistors, an SG90 micro servo and about 15 jumper wires.

Insert the blue LED. Then connect its long leg through a resistor to pin 12, and its short leg to the ground rail.
Do the same for the yellow LED, but use pin 13.
The servo has three wires. Connect the signal wire (orange or yellow) to pin 8, ground (brown or black) to the ground rail and power (red) to 5V.
Check that no stray wire bridges two rows, then plug the Arduino into your PC.
Finally, open Device Manager → Ports (COM & LPT) and note the COM port, for example COM3.

Power note: a servo bigger than an SG90 can pull too much current from the Arduino’s 5V pin and make the board reset. If the LEDs flicker when the servo moves, give the servo its own 5V supply and connect the grounds together.

Step 2: Upload the Arduino sketch

Install the Arduino IDE and open it.
Under Tools → Board, choose Arduino Uno. Then pick your COM port under Tools → Port.
Open hardware/jarvis_hardware/jarvis_hardware.ino. It listens for single letters over USB: 0 for idle, B for researching, Y for debating and W for complete.
Click Verify, then Upload, and wait for “Done uploading”.
Close the Serial Monitor before you start the Python app, because only one program can use the port at a time.

Step 3: Set up Python

Install Python 3.11 or newer. Then open a terminal in the project folder, create a virtual environment with python -m venv venv and activate it with venv\Scripts\activate. Next, install the packages:

pip install flask flask-socketio flask-cors python-dotenv requests pyserial ddgs

Then check that python -c "import serial; serial.Serial" runs without errors. If it says module 'serial' has no attribute 'Serial', two packages are fighting over the same name. Remove both and reinstall the right one:

pip uninstall -y serial pyserial
pip install pyserial

Step 4: Create the .env file

Settings go in a .env file in the project folder, so they stay out of the code:

ARDUINO_PORT=COM3, with your own port from Step 1.
OLLAMA_URL=http://localhost:11434/api/chat, which is Ollama’s default address.
OMNIVOICE_URL=http://localhost:3900/v1, which is OmniVoice Studio’s local API.
CACHE_TTL=3600, so repeated replies are cached for an hour.
SECRET_KEY is optional. Then add OMNIVOICE_VOICE in Step 6 and the CrewAI values in Step 7.

Add .env to .gitignore straight away, because it will soon hold a secret token.

Step 5: Install Ollama

Ollama runs AI models on your own computer. Install it from ollama.com, and it starts in the background. Then pick a model that fits your graphics card. Check its memory with nvidia-smi --query-gpu=memory.total --format=csv:

Up to 4 GB: ollama pull qwen2.5-coder:1.5b
8 GB: ollama pull llama3.1:8b

Then test it with ollama run <model-name>. You can also pin a model with OVERRIDE_MODEL in .env.

Step 6: Install OmniVoice Studio

OmniVoice Studio gives Jarvis a voice, and it runs locally too. Download the Windows installer from its GitHub page, run it, and let the first-run wizard download the voice models. This can take several minutes.

If setup fails with “Backend process exited”, read the real error in %APPDATA%\OmniVoice\omnivoice.log.
If the log shows the voice engine running out of graphics memory, switch to KittenTTS under Settings → Engines → TTS. It’s small and runs on the CPU.
Then open http://localhost:3900/v1/audio/voices in a browser. If you see JSON, the API works.
Pick a voice in Settings → Voice Gallery and put its id in OMNIVOICE_VOICE. KittenTTS includes four male and four female voices.

You can close OmniVoice afterwards, because the app starts it automatically. A cold start takes 15 to 75 seconds, so the first reply may be slow.

Running OmniVoice from source instead

You can also run it from source. First check that Git and Python are installed:

git --version
python3 --version
pip3 --version

Then clone the project, create a virtual environment and install its requirements. On Windows, activate the environment with venv\Scripts\activate instead:

git clone https://github.com/debpalash/OmniVoice-Studio.git
cd OmniVoice-Studio

python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt

Check the project’s README for the start command and any .env settings. If you get “No module named X”, install that package with pip install X. If the port is already in use, stop the old process first.

Step 7: Set up the CrewAI agents

CrewAI lets several AI agents work together. In CrewAI Studio, create a blank project called Jarvis hardware program:

Then add two agents:

Lead Intelligence Gatherer. Its goal is to find accurate, up-to-date information about the topic. Give it the Brave Search tool.
Senior Executive Analyst (Jarvis). Its goal is to turn raw findings into a clear briefing. Tell it never to include raw commands or code, only clean, professional text.

Next, create two tasks. The first collects the facts the user’s question needs, as a bulleted list. The second turns that list into a short, conversational answer with no code blocks:

Then connect the agents to their tasks, test the crew and publish it:

When it’s deployed, copy its kickoff URL and bearer token into .env:

CREWAI_CREW_URL=your crew urlCREWAI_CREW_TOKEN=your crew token

To be clear about the current state: the app builds the CrewAI login header, but no route calls the crew yet. Connecting chat messages to a crew run is the next piece of work.

The J.A.R.V.I.S. Software

The HTML dashboard

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>J.A.R.V.I.S. Interface</title>
    <link rel="stylesheet" href="/static/style.css">
</head>
<body>

    <div class="app-container">

        <!-- Left Sidebar: Hardware Status & TTS -->
        <aside class="hardware-sidebar">
            <div class="sidebar-header">
                <h2>HARDWARE<br>TELEMETRY</h2>
            </div>

            <div class="orb-container">
                <div id="main-orb" class="status-orb orb-idle"></div>
                <p id="status-text" class="status-label">STANDBY</p>
                <p id="sub-status-text" class="status-sub-label">System Idle</p>
            </div>

            <div class="hardware-map">
                <p class="map-title">PIN STATES</p>
                <div class="map-item">
                    <span class="pin-indicator" id="pin-12"></span> 
                    <span>PIN 12 (Research)</span>
                </div>
                <div class="map-item">
                    <span class="pin-indicator" id="pin-13"></span> 
                    <span>PIN 13 (Debate)</span>
                </div>
                <div class="map-item">
                    <span class="pin-indicator" id="relay-1"></span> 
                    <span>RELAY 1 (Complete)</span>
                </div>
            </div>

            <!-- NEW: EXPLICIT TEXT-TO-SPEECH MODULE -->
            <div class="tts-panel">
                <p class="map-title">VOICE SYNTHESIZER</p>
                <textarea id="manual-tts-input" placeholder="Type text here to test the voice..."></textarea>
                <button id="manual-speak-btn">SPEAK</button>
            </div>

            <div class="system-info">
                <p>CREW AI: <span class="text-success">ONLINE</span></p>
                <p>TTS ENGINE: <span class="text-success">ACTIVE</span></p>
            </div>
        </aside>

        <!-- Main Area: Chat Interface -->
        <main class="chat-main">

            <header class="chat-header">
                <h1>J.A.R.V.I.S.</h1>
                <p>Conversational Task Deployment Interface</p>
            </header>

            <div class="chat-messages" id="chat-log">
                <div class="message jarvis-message">
                    <div class="message-content">
                        {{ boot_greeting }}
                        <button class="inline-speak-btn">🔊</button>
                    </div>
                </div>
            </div>

            <footer class="chat-input-area">
                <div class="input-wrapper">
                    <input id="user-input" type="text" placeholder="Type a message to J.A.R.V.I.S..." autocomplete="off" />
                    <button id="send-btn" title="Send Message">
                        <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"></line><polygon points="22 2 15 22 11 13 2 9 22 2"></polygon></svg>
                    </button>
                </div>
            </footer>

        </main>
    </div>

    <script src="https://cdn.socket.io/4.7.5/socket.io.min.js"></script>
    <script src="/static/script.js" defer></script>
</body>
</html>

The status orb is the main indicator. JavaScript swaps its classes, so it looks idle, busy or speaking.
The ids pin-12, pin-13 and relay-1 mark the on-screen copies of the LEDs and servo, so the page can mirror the real hardware.
{{ boot_greeting }} is filled in by Flask before the page reaches the browser.
Finally, the Socket.IO scripts keep a live connection open, so updates arrive without reloading.

The CSS

/* --- Reset & Base --- */
:root {
    --bg-dark: #050810;
    --bg-sidebar: #0a0f1a;
    --bg-chat: #080c15;
    --primary-cyan: #00d4ff;
    --text-main: #e2e8f0;
    --text-dim: #64748b;
    --blue-glow: #3b82f6;
    --yellow-glow: #eab308;
    --white-glow: #ffffff;
    --user-bubble: #1e293b;
}

* { box-sizing: border-box; margin: 0; padding: 0; }

body {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
    background-color: var(--bg-dark);
    color: var(--text-main);
    height: 100vh;
    width: 100vw;
    overflow: hidden;
}

.app-container { display: flex; height: 100vh; width: 100vw; }

/* --- Sidebar --- */
.hardware-sidebar {
    width: 340px;
    min-width: 340px;
    background-color: var(--bg-sidebar);
    border-right: 1px solid #1e293b;
    display: flex;
    flex-direction: column;
    padding: 2rem;
    box-shadow: 4px 0 15px rgba(0,0,0,0.5);
    overflow-y: auto;
}

.sidebar-header h2 {
    font-size: 1.2rem;
    letter-spacing: 3px;
    color: var(--primary-cyan);
    margin-bottom: 2.5rem;
    line-height: 1.5;
}

.orb-container {
    display: flex;
    flex-direction: column;
    align-items: center;
    margin-bottom: 3rem;
}

.status-orb {
    width: 160px;
    height: 160px;
    border-radius: 50%;
    transition: all 1s ease-in-out;
    margin-bottom: 1.5rem;
}

.orb-idle { background: radial-gradient(circle at 30% 30%, #4b5563, #111827); box-shadow: 0 0 20px rgba(75, 85, 99, 0.2); }
.orb-researching { background: radial-gradient(circle at 30% 30%, #93c5fd, #1e3a8a); box-shadow: 0 0 60px var(--blue-glow), inset 0 0 20px rgba(59, 130, 246, 0.5); animation: pulse-blue 2s infinite; }
.orb-debating { background: radial-gradient(circle at 30% 30%, #fde047, #854d0e); box-shadow: 0 0 60px var(--yellow-glow), inset 0 0 20px rgba(234, 179, 8, 0.5); animation: pulse-yellow 1.5s infinite; }
.orb-complete { background: radial-gradient(circle at 30% 30%, #ffffff, #94a3b8); box-shadow: 0 0 80px var(--white-glow), inset 0 0 20px rgba(255, 255, 255, 0.8); }

@keyframes pulse-blue { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.05); } }
@keyframes pulse-yellow { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.08); } }

.status-label { font-size: 1.4rem; font-weight: bold; letter-spacing: 2px; }
.status-sub-label { font-size: 0.9rem; color: var(--text-dim); margin-top: 0.5rem; }

.hardware-map { margin-bottom: 2rem; }
.map-title { font-size: 0.8rem; color: var(--text-dim); letter-spacing: 2px; margin-bottom: 1.5rem; border-bottom: 1px solid #1e293b; padding-bottom: 0.5rem; }
.map-item { display: flex; align-items: center; gap: 1rem; margin-bottom: 1rem; font-size: 0.95rem; color: #94a3b8; }

.pin-indicator {
    width: 12px; height: 12px; border-radius: 50%;
    background-color: #334155;
    transition: all 0.5s;
}
.pin-indicator.active-blue { background-color: var(--blue-glow); box-shadow: 0 0 10px var(--blue-glow); }
.pin-indicator.active-yellow { background-color: var(--yellow-glow); box-shadow: 0 0 10px var(--yellow-glow); }
.pin-indicator.active-white { background-color: var(--white-glow); box-shadow: 0 0 10px var(--white-glow); }

/* NEW: TTS Panel Styles */
.tts-panel {
    background: rgba(15, 23, 42, 0.5);
    border: 1px solid #1e293b;
    border-radius: 8px;
    padding: 1rem;
    margin-bottom: 2rem;
}

.tts-panel textarea {
    width: 100%;
    height: 80px;
    background: #0f172a;
    border: 1px solid #334155;
    border-radius: 4px;
    color: var(--text-main);
    padding: 0.5rem;
    font-family: inherit;
    font-size: 0.9rem;
    resize: none;
    margin-bottom: 0.75rem;
    outline: none;
}

.tts-panel textarea:focus { border-color: var(--primary-cyan); }

.tts-panel button {
    width: 100%;
    background: transparent;
    border: 1px solid var(--primary-cyan);
    color: var(--primary-cyan);
    padding: 0.6rem;
    border-radius: 4px;
    font-weight: bold;
    letter-spacing: 1px;
    cursor: pointer;
    transition: all 0.3s;
}

.tts-panel button:hover { background: rgba(0, 212, 255, 0.15); }

.system-info { font-size: 0.85rem; color: var(--text-dim); margin-top: auto; }
.text-success { color: #22c55e; }

/* --- Main Chat Area --- */
.chat-main {
    flex: 1;
    display: flex;
    flex-direction: column;
    background-color: var(--bg-chat);
    background-image: 
        linear-gradient(rgba(0, 212, 255, 0.03) 1px, transparent 1px),
        linear-gradient(90deg, rgba(0, 212, 255, 0.03) 1px, transparent 1px);
    background-size: 40px 40px;
}

.chat-header {
    padding: 2rem 3rem;
    border-bottom: 1px solid #1e293b;
    background: rgba(8, 12, 21, 0.8);
    backdrop-filter: blur(10px);
}
.chat-header h1 { font-size: 2rem; letter-spacing: 4px; color: var(--primary-cyan); }
.chat-header p { color: var(--text-dim); margin-top: 0.5rem; font-size: 1rem; }

.chat-messages {
    flex: 1;
    overflow-y: auto;
    padding: 3rem;
    display: flex;
    flex-direction: column;
    gap: 2rem;
}
.chat-messages::-webkit-scrollbar { width: 8px; }
.chat-messages::-webkit-scrollbar-track { background: transparent; }
.chat-messages::-webkit-scrollbar-thumb { background: #1e293b; border-radius: 4px; }

.message { display: flex; max-width: 80%; animation: fadeIn 0.3s ease-in; }
@keyframes fadeIn { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }

.jarvis-message { align-self: flex-start; }
.user-message { align-self: flex-end; }

.message-content {
    padding: 1.5rem 2rem;
    border-radius: 1.5rem;
    font-size: 1.1rem;
    line-height: 1.6;
    position: relative;
}

.jarvis-message .message-content {
    background: rgba(15, 23, 42, 0.6);
    border: 1px solid rgba(0, 212, 255, 0.2);
    border-bottom-left-radius: 0.3rem;
    color: #e2e8f0;
}

.user-message .message-content {
    background: var(--user-bubble);
    border: 1px solid #334155;
    border-bottom-right-radius: 0.3rem;
    color: #f8fafc;
}

/* NEW: Inline Speak Button Style */
.inline-speak-btn {
    position: absolute;
    bottom: 10px;
    right: 15px;
    background: rgba(0, 0, 0, 0.3);
    border: 1px solid rgba(255,255,255,0.1);
    border-radius: 50%;
    width: 35px;
    height: 35px;
    cursor: pointer;
    font-size: 16px;
    display: flex;
    align-items: center;
    justify-content: center;
    opacity: 0.5;
    transition: all 0.3s;
}
.inline-speak-btn:hover { opacity: 1; background: rgba(0, 212, 255, 0.2); border-color: var(--primary-cyan); }

/* Input Area */
.chat-input-area {
    padding: 2rem 3rem;
    background: rgba(8, 12, 21, 0.9);
    border-top: 1px solid #1e293b;
}
.input-wrapper {
    display: flex;
    background: #0f172a;
    border: 1px solid #334155;
    border-radius: 1rem;
    padding: 0.5rem 0.5rem 0.5rem 2rem;
    transition: border-color 0.3s;
}
.input-wrapper:focus-within { border-color: var(--primary-cyan); box-shadow: 0 0 15px rgba(0, 212, 255, 0.15); }
.input-wrapper input {
    flex: 1;
    background: transparent;
    border: none;
    outline: none;
    color: var(--text-main);
    font-size: 1.2rem;
    font-family: inherit;
}
.input-wrapper input::placeholder { color: #475569; }
.input-wrapper button {
    background: var(--primary-cyan);
    color: #000;
    border: none;
    border-radius: 0.7rem;
    width: 50px; height: 50px;
    cursor: pointer;
    display: flex; align-items: center; justify-content: center;
    transition: background 0.3s;
}
.input-wrapper button:hover { background: #33e0ff; }

At the top, colour variables keep the design consistent, because changing one colour updates the whole dashboard. Meanwhile, the orb animations pulse while the agents work, the pin styles glow blue, yellow or white to match the hardware, and the chat bubbles put your messages on the right and Jarvis’s on the left.

The JavaScript

// --- DOM Elements ---
const chatLog = document.getElementById('chat-log');
const userInput = document.getElementById('user-input');
const sendBtn = document.getElementById('send-btn');
const manualTtsInput = document.getElementById('manual-tts-input');
const manualSpeakBtn = document.getElementById('manual-speak-btn');

const orb = document.getElementById('main-orb');
const statusText = document.getElementById('status-text');
const subStatusText = document.getElementById('sub-status-text');

const pin12 = document.getElementById('pin-12');
const pin13 = document.getElementById('pin-13');
const relay1 = document.getElementById('relay-1');

// --- Global TTS Function ---
// Made global so the HTML onclick can call it directly for the first message.
// Voice synthesis runs through OmniVoice Studio (local, OpenAI-compatible TTS
// server) via the /tts backend route, instead of the browser's speechSynthesis.
let currentAudio = null;
let speakRequestId = 0;

async function speakText(text) {
    const cleanText = text.replace(/\*/g, '');
    if (!cleanText) return;

    // Claim this call as the authoritative one and stop whatever's already
    // playing. Generation takes several seconds, so if speakText() gets
    // called again before this call's fetch resolves (e.g. auto-play on
    // load overlapping a manual speaker click), the requestId check below
    // makes the earlier call drop its result instead of also playing --
    // otherwise both would end up playing at once, overlapping out of sync.
    const requestId = ++speakRequestId;
    if (currentAudio) {
        currentAudio.pause();
        currentAudio = null;
    }

    // Voice synthesis on this hardware can take several seconds -- show
    // visible feedback so it doesn't look hung.
    const previousSubStatus = subStatusText.textContent;
    subStatusText.textContent = 'Synthesizing voice...';

    try {
        const resp = await fetch('/tts', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ text: cleanText }),
        });
        if (!resp.ok) {
            const data = await resp.json().catch(() => ({}));
            throw new Error(data.error || `TTS request failed (${resp.status})`);
        }
        const blob = await resp.blob();
        if (requestId !== speakRequestId) return; // superseded by a newer call
        currentAudio = new Audio(URL.createObjectURL(blob));
        currentAudio.play().catch(() => {}); // autoplay may be blocked before user interaction
    } catch (err) {
        console.error('Voice synthesis failed:', err);
    } finally {
        if (requestId === speakRequestId) {
            subStatusText.textContent = previousSubStatus;
        }
    }
}

// --- Manual TTS Sidebar Button ---
manualSpeakBtn.addEventListener('click', () => {
    const text = manualTtsInput.value.trim();
    if(text) {
        speakText(text);
    }
});

// --- Hardware State Management ---
function setHardwareState(state) {
    orb.classList.remove('orb-idle', 'orb-researching', 'orb-debating', 'orb-complete');
    pin12.classList.remove('active-blue');
    pin13.classList.remove('active-yellow');
    relay1.classList.remove('active-white');

    switch(state) {
        case 'researching':
            orb.classList.add('orb-researching');
            pin12.classList.add('active-blue');
            statusText.textContent = 'RESEARCHING';
            subStatusText.textContent = 'Agents gathering data...';
            break;
        case 'debating':
            orb.classList.add('orb-debating');
            pin13.classList.add('active-yellow');
            statusText.textContent = 'DEBATING';
            subStatusText.textContent = 'Agents evaluating options...';
            break;
        case 'complete':
            orb.classList.add('orb-complete');
            relay1.classList.add('active-white');
            statusText.textContent = 'TASK COMPLETE';
            subStatusText.textContent = 'Ready for next command.';
            break;
        default:
            orb.classList.add('orb-idle');
            statusText.textContent = 'STANDBY';
            subStatusText.textContent = 'System Idle';
    }
}

// --- Chat Logic ---
function addMessage(text, sender) {
    const messageDiv = document.createElement('div');
    messageDiv.classList.add('message', `${sender}-message`);

    const contentDiv = document.createElement('div');
    contentDiv.classList.add('message-content');
    contentDiv.innerText = text; 

    // If it's from Jarvis, add the explicit Speak button
    if(sender === 'jarvis') {
        const speakBtn = document.createElement('button');
        speakBtn.classList.add('inline-speak-btn');
        speakBtn.innerText = '🔊';
        speakBtn.addEventListener('click', (e) => {
            e.stopPropagation();
            speakText(text);
        });
        contentDiv.appendChild(speakBtn);
    }

    messageDiv.appendChild(contentDiv);
    chatLog.appendChild(messageDiv);
    chatLog.scrollTo({ top: chatLog.scrollHeight, behavior: "smooth" });
}

// --- SocketIO: live hardware state pushed from the backend ---
const socket = io();
socket.on('status_update', (data) => setHardwareState(data.state));

async function fetchJarvisResponse(userText) {
    const resp = await fetch('/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message: userText }),
    });

    const data = await resp.json();
    if (!resp.ok) {
        throw new Error(data.error || `Request failed (${resp.status})`);
    }
    return data.reply;
}

const defaultInputPlaceholder = userInput.placeholder;

async function handleSend() {
    const text = userInput.value.trim();
    if (!text) return;

    addMessage(text, 'user');
    userInput.value = '';
    sendBtn.disabled = true;
    userInput.disabled = true;
    userInput.placeholder = 'Jarvis is responding...';

    try {
        const response = await fetchJarvisResponse(text);
        addMessage(response, 'jarvis');
    } catch (err) {
        addMessage(`Apologies, I encountered an error: ${err.message}`, 'jarvis');
    } finally {
        sendBtn.disabled = false;
        userInput.disabled = false;
        userInput.placeholder = defaultInputPlaceholder;
        userInput.focus();
    }
}

// Event Listeners
sendBtn.addEventListener('click', handleSend);
userInput.addEventListener('keypress', (e) => {
    if (e.key === 'Enter') handleSend();
});

setHardwareState('idle');

// --- Boot greeting: speak the initial message once the page loads.
// Best effort -- browsers may block audio autoplay until the user has
// interacted with the page, so a failure here is silently ignored.
function getBootGreetingText() {
    const greetingEl = document.querySelector('#chat-log .message-content');
    if (!greetingEl) return '';
    const clone = greetingEl.cloneNode(true);
    clone.querySelector('.inline-speak-btn')?.remove();
    return clone.textContent.trim();
}

document.querySelector('#chat-log .inline-speak-btn')?.addEventListener('click', (e) => {
    e.stopPropagation();
    const greetingText = getBootGreetingText();
    if (greetingText) speakText(greetingText);
});

window.addEventListener('load', () => {
    const greetingText = getBootGreetingText();
    if (greetingText) speakText(greetingText);
});

First, the voice code sends each reply to OmniVoice and plays the audio. It also stops any older audio first, so voices never overlap.
Next, the UI controller clears the current state and then lights the orb and pin indicators for the new one.
Then the Socket.IO listener hears state changes from Python and updates the screen at once.
Finally, the chat function sends your message to the server and shows the reply when it arrives.

The Python server

import os
import re
import time
import logging
import subprocess
import threading
import hashlib
import html
import requests
import serial
import serial.tools.list_ports
from collections import OrderedDict
from datetime import date, datetime, timezone
from dotenv import load_dotenv
from ddgs import DDGS
from flask import Flask, render_template, request, jsonify, abort, Response
from flask_socketio import SocketIO, emit  # <-- ADDED

load_dotenv(override=True)

# ── LOGGING ───────────────────────────────────────────────────
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(funcName)s:%(lineno)d %(message)s",
    datefmt="%H:%M:%S",
)
log = logging.getLogger(__name__)

app = Flask(__name__, static_folder="static", template_folder="templates")
app.secret_key = os.getenv("SECRET_KEY") or os.urandom(32)

# ── ADDED: SOCKETIO SETUP ─────────────────────────────────────
socketio = SocketIO(app, cors_allowed_origins="*", async_mode="threading")

# ── CONFIGURATION ──────────────────────────────────────────────
CREWAI_CREW_URL   = os.getenv("CREWAI_CREW_URL", "")
CREWAI_CREW_TOKEN = os.getenv("CREWAI_CREW_TOKEN", "")
CREWAI_KICKOFF_URL = f"{CREWAI_CREW_URL}/kickoff" if CREWAI_CREW_URL else ""
CREWAI_STATUS_URL  = f"{CREWAI_CREW_URL}/status/{{kickoff_id}}" if CREWAI_CREW_URL else ""
# The input variable name your crew's task prompts expect (e.g. a task
# written as "Research {topic}..." needs CREWAI_INPUT_KEY=topic). Defaults
# to "query" -- adjust in .env to match your actual crew, not this code.
CREWAI_INPUT_KEY = os.getenv("CREWAI_INPUT_KEY", "query")
CREWAI_POLL_INTERVAL_SECONDS = 5
CREWAI_POLL_TIMEOUT_SECONDS = 240

OLLAMA_URL = os.getenv("OLLAMA_URL", "http://localhost:11434/api/chat")
DEBUG_MODE = os.getenv("FLASK_DEBUG", "1") == "1"

# OmniVoice Studio -- local, OpenAI-compatible TTS server (no API key needed).
# https://github.com/debpalash/OmniVoice-Studio
OMNIVOICE_URL = os.getenv("OMNIVOICE_URL", "http://localhost:3900/v1")
OMNIVOICE_VOICE = os.getenv("OMNIVOICE_VOICE", "alloy")

# ── ARDUINO SERIAL SETUP ──────────────────────────────────────
def _find_arduino_port() -> str | None:
    """Try the env-specified port first, then scan all COM ports for an Arduino."""
    env_port = os.getenv("ARDUINO_PORT", "")
    candidates = []

    if env_port:
        candidates.append(env_port)

    for p in serial.tools.list_ports.comports():
        desc = (p.description or "").lower()
        if any(kw in desc for kw in ("arduino", "ch340", "cp210", "usb serial")):
            if p.device not in candidates:
                candidates.append(p.device)

    for p in serial.tools.list_ports.comports():
        if p.device not in candidates:
            candidates.append(p.device)

    log.info(f"[HARDWARE] Port candidates to try: {candidates}")
    for port in candidates:
        try:
            conn = serial.Serial(port=port, baudrate=9600, timeout=1)
            time.sleep(2) 
            log.info(f"🔌 [HARDWARE] Connected successfully on {port}.")
            return conn
        except Exception as e:
            log.debug(f"[HARDWARE] {port} failed: {e}")

    return None

# Flask's debug reloader runs this module twice: once as a watcher process
# that never exits, and once as the actual server (marked by WERKZEUG_RUN_MAIN).
# Only open the serial port in the process that's actually serving requests,
# otherwise the watcher holds it open and the real server can never connect.
_should_connect_hardware = not DEBUG_MODE or os.environ.get("WERKZEUG_RUN_MAIN") == "true"

arduino = _find_arduino_port() if _should_connect_hardware else None
if arduino is None and _should_connect_hardware:
    log.warning("⚠️ [HARDWARE] No Arduino found on any port. Software-only mode enabled.")

# ── OMNIVOICE AUTO-LAUNCH ──────────────────────────────────────
OMNIVOICE_APP_PATH = os.getenv(
    "OMNIVOICE_APP_PATH", r"C:\Program Files\OmniVoice Studio\omnivoice-studio.exe"
)

def _ensure_omnivoice_running():
    """Launch OmniVoice Studio in the background if its API isn't already up.
    Its own backend takes ~10-15s to finish loading, so this doesn't wait --
    /tts just returns a clear error until it's ready."""
    try:
        requests.get(f"{OMNIVOICE_URL}/audio/voices", timeout=2)
        log.info("🔊 [OMNIVOICE] Already running.")
        return
    except Exception:
        pass

    if not os.path.exists(OMNIVOICE_APP_PATH):
        log.warning(
            f"⚠️ [OMNIVOICE] Not running and no executable found at {OMNIVOICE_APP_PATH}. "
            "Set OMNIVOICE_APP_PATH in .env if it's installed elsewhere."
        )
        return

    try:
        subprocess.Popen([OMNIVOICE_APP_PATH], close_fds=True)
        log.info("🔊 [OMNIVOICE] Not running -- launching it in the background.")
    except Exception as e:
        log.error(f"❌ [OMNIVOICE] Failed to launch: {e}")

if _should_connect_hardware:
    _ensure_omnivoice_running()

# ── MODIFIED: JARVIS HARDWARE STATES ──────────────────────────
def trigger_hardware_state(state: str):
    """Sends signals to Arduino based on JARVIS UI states and emits to Web UI."""
    signals = {
        "idle": "0",
        "researching": "B", # Blue LED
        "debating": "Y",    # Yellow LED
        "complete": "W"     # White LED / Relay
    }

    sig = signals.get(state, "0")

    # 1. Push visual update to the Web UI instantly via WebSocket
    socketio.emit('status_update', {'state': state})

    # 2. Push physical update to Arduino
    if not arduino or not arduino.is_open:
        return

    try:
        arduino.write(sig.encode('utf-8'))
        log.info(f"🔌 [HARDWARE] Sent '{sig}' -> State: {state.upper()}")
    except Exception as e:
        log.error(f"❌ Failed writing to serial interface: {e}")
        _reconnect_arduino()

def _reconnect_arduino():
    """A write failure usually means the board dropped off and Windows
    re-enumerated it on a new COM port (often a brownout from something like
    a servo drawing too much current off the board's own 5V rail during a
    long-running state) -- the old handle is dead for the rest of the
    process otherwise, so re-scan and pick up wherever it lands."""
    global arduino
    try:
        if arduino:
            arduino.close()
    except Exception:
        pass
    arduino = _find_arduino_port()
    if arduino is None:
        log.warning("⚠️ [HARDWARE] Reconnect failed -- no Arduino found. Software-only mode until next successful signal.")

# ── RATE LIMITER ──────────────────────────────────────────────
class RateLimiter:
    def __init__(self, max_requests: int = 10, window_seconds: int = 60):
        self.max_requests = max_requests
        self.window = window_seconds
        self._requests: dict[str, list[float]] = {}
        self._lock = threading.Lock()

    def is_allowed(self, key: str) -> bool:
        now = time.time()
        with self._lock:
            if key not in self._requests:
                self._requests[key] = []
            self._requests[key] = [t for t in self._requests[key] if now - t < self.window]
            if len(self._requests[key]) >= self.max_requests:
                return False
            self._requests[key].append(now)
            return True

rate_limiter = RateLimiter(max_requests=10, window_seconds=60)

# ── BOUNDED LRU CACHE ────────────────────────────────────────
class LRUCache:
    def __init__(self, ttl: int = 3600, max_size: int = 128):
        self.ttl = ttl
        self.max_size = max_size
        self._store: OrderedDict[str, tuple[float, dict]] = OrderedDict()
        self._lock = threading.Lock()

    def get(self, key: str):
        with self._lock:
            if key not in self._store: return None
            ts, data = self._store[key]
            if time.time() - ts > self.ttl:
                del self._store[key]
                return None
            self._store.move_to_end(key)
            return data

    def set(self, key: str, data: dict):
        with self._lock:
            if key in self._store:
                del self._store[key]
            elif len(self._store) >= self.max_size:
                self._store.popitem(last=False) 
            self._store[key] = (time.time(), data)

cache = LRUCache(ttl=int(os.getenv("CACHE_TTL", 3600)), max_size=128)
# OmniVoice's own synthesis takes several seconds regardless of engine choice
# (measured, not our overhead) -- cache generated audio so repeated lines
# (e.g. the boot greeting, replayed on every page load) are instant after
# the first generation.
tts_cache = LRUCache(ttl=int(os.getenv("CACHE_TTL", 3600)), max_size=64)

# ── GPU TIER SYSTEM ──────────────────────────────────────────
GPU_TIERS = [
    {"min_vram": 48, "model": "qwen2.5:72b",      "num_ctx": 32768, "num_batch": 2048, "search_results": 10},
    {"min_vram": 40, "model": "llama3.3:70b",      "num_ctx": 32768, "num_batch": 2048, "search_results": 10},
    {"min_vram": 32, "model": "qwen2.5:32b",       "num_ctx": 24576, "num_batch": 1024, "search_results": 8},
    {"min_vram": 24, "model": "qwen2.5:32b",       "num_ctx": 16384, "num_batch": 1024, "search_results": 8},
    {"min_vram": 16, "model": "qwen2.5:14b",       "num_ctx": 16384, "num_batch": 512,  "search_results": 7},
    {"min_vram": 12, "model": "qwen2.5:14b",       "num_ctx": 4096,  "num_batch": 512,  "search_results": 5},
    {"min_vram": 8,  "model": "llama3.1:8b",       "num_ctx": 8192,  "num_batch": 256,  "search_results": 5},
    {"min_vram": 0,  "model": "qwen2.5-coder:1.5b","num_ctx": 4096,  "num_batch": 128,  "search_results": 4},
]

OVERRIDE_MODEL = os.getenv("OVERRIDE_MODEL", "")

def detect_gpu_vram() -> float:
    try:
        result = subprocess.run(
            ["nvidia-smi", "--query-gpu=memory.total", "--format=csv,noheader,nounits"],
            capture_output=True, text=True, timeout=5,
        )
        if result.returncode == 0 and result.stdout.strip():
            total_mb = sum(int(line.strip()) for line in result.stdout.strip().split("\n") if line.strip().isdigit())
            return round(total_mb / 1024, 1)
    except Exception: pass
    return 0.0

def select_gpu_tier(vram_gb: float) -> dict:
    for tier in GPU_TIERS:
        if vram_gb >= tier["min_vram"]:
            selected = dict(tier)
            if OVERRIDE_MODEL: selected["model"] = OVERRIDE_MODEL
            selected["num_thread"] = 4
            selected["keep_alive"] = os.getenv("OLLAMA_KEEP_ALIVE", "5m")
            selected["temperature"] = 0.7 # Slightly higher for conversational chat
            return selected
    return dict(GPU_TIERS[-1])

GPU_VRAM = detect_gpu_vram()
GPU_CONFIG = select_gpu_tier(GPU_VRAM)

log.info("═" * 50)
log.info(f"   GPU VRAM: {GPU_VRAM}GB")
log.info(f"   Selected Model: {GPU_CONFIG['model']}")
log.info(f"   Context Window: {GPU_CONFIG['num_ctx']} tokens")
log.info("═" * 50)

# ── JARVIS CHAT PROMPT ────────────────────────────────────────
JARVIS_SYSTEM_PROMPT = """You are J.A.R.V.I.S., a highly advanced, professional AI assistant created by Tony Stark. 
You are helpful, concise, and use modern technology terminology. You have access to live internet search results to answer questions accurately.
Do not use markdown headers like # or ##. Just provide well-structured plain text responses."""

BOOT_GREETING = (
    "Good evening, sir. Diagnostics complete, all systems nominal, "
    "and I've taken the liberty of standing by. How may I be of service?"
)

# ── HELPERS ────────────────────────────────────────────────────
def get_crew_headers() -> dict:
    return {"Authorization": f"Bearer {CREWAI_CREW_TOKEN}", "Content-Type": "application/json"}

STOP_WORDS = {"and", "or", "the", "a", "an", "of", "in", "on", "at", "to", "for", "is", "are", "was", "were", "with", "how", "what", "why", "who"}

def topic_keywords(topic: str) -> list[str]:
    words = re.findall(r"[a-zA-Z0-9]+", topic.lower())
    return [w for w in words if w not in STOP_WORDS and len(w) > 2] or [topic.lower()]

def sanitize_topic(topic: str) -> str:
    topic = re.sub(r"<[^>]*>", "", topic)
    topic = html.escape(topic)
    topic = re.sub(r"[\x00-\x1f\x7f]", "", topic)
    return re.sub(r"\s+", " ", topic).strip()

def sanitize_speech_text(text: str) -> str:
    text = re.sub(r"<[^>]*>", "", text)
    text = re.sub(r"[\x00-\x1f\x7f]", "", text)
    return re.sub(r"\s+", " ", text).strip()

def topic_specific_search(topic: str, max_results: int = 5) -> str:
    keywords = topic_keywords(topic)
    if not keywords: return "No specific keywords found."
    query = " ".join(keywords[:5])

    try:
        with DDGS() as ddgs:
            results = list(ddgs.text(query, max_results=max_results))
        if not results: return f"No search results found for {topic}."
        return "\n---\n".join([f"Title: {r.get('title', '')}\nSummary: {r.get('body', '')}" for r in results])
    except Exception as e:
        log.warning(f"Search failed: {e}")
        return "Search engine unavailable."

def crewai_research(topic: str) -> str:
    """Kick off the configured Crew and poll for its result. Falls back to
    the direct DDGS search if CrewAI isn't configured, or if the run errors
    out or exceeds the poll timeout -- so /chat still works without a crew."""
    if not CREWAI_CREW_URL:
        return topic_specific_search(topic)

    try:
        kickoff = requests.post(
            CREWAI_KICKOFF_URL,
            headers=get_crew_headers(),
            json={"inputs": {CREWAI_INPUT_KEY: topic}},
            timeout=15,
        )
        kickoff.raise_for_status()
        kickoff_data = kickoff.json()
        kickoff_id = kickoff_data.get("kickoff_id") or kickoff_data.get("crew_id")
        if not kickoff_id:
            raise ValueError(f"No kickoff_id in kickoff response: {kickoff_data}")

        deadline = time.time() + CREWAI_POLL_TIMEOUT_SECONDS
        while time.time() < deadline:
            time.sleep(CREWAI_POLL_INTERVAL_SECONDS)
            status_resp = requests.get(
                CREWAI_STATUS_URL.format(kickoff_id=kickoff_id),
                headers=get_crew_headers(),
                timeout=15,
            )
            status_resp.raise_for_status()
            status_data = status_resp.json()
            state = status_data.get("status")

            if state == "completed":
                result = status_data.get("result") or status_data.get("output") or ""
                return str(result) if result else "The research crew completed but returned no result."
            if state == "failed":
                raise RuntimeError(status_data.get("error", "Crew run failed with no error detail."))

        raise TimeoutError(f"Crew run did not complete within {CREWAI_POLL_TIMEOUT_SECONDS}s.")
    except Exception as e:
        log.warning(f"⚠️ [CREWAI] Research run failed, falling back to direct search: {e}")
        return topic_specific_search(topic)

def ollama_chat(messages: list, retries: int = 2) -> str:
    payload = {
        "model": GPU_CONFIG["model"], "messages": messages, "stream": False,
        "keep_alive": GPU_CONFIG["keep_alive"],
        "options": {"temperature": GPU_CONFIG["temperature"], "num_ctx": GPU_CONFIG["num_ctx"], "num_batch": GPU_CONFIG["num_batch"]}
    }
    for attempt in range(retries + 1):
        try:
            timeout = 120 + (GPU_CONFIG["num_ctx"] // 1024) * 30
            resp = requests.post(OLLAMA_URL, json=payload, timeout=timeout)
            resp.raise_for_status()
            return resp.json().get("message", {}).get("content", "").strip()
        except Exception as e:
            log.warning(f"Ollama failure: {e}")
            time.sleep(3 ** attempt)
    return "I apologize, but I'm having trouble reaching my reasoning engine right now. Please try again shortly."

# ── ROUTES ─────────────────────────────────────────────────────
@app.route("/")
def index():
    return render_template("index.html", boot_greeting=BOOT_GREETING)

@app.route("/chat", methods=["POST"])
def chat():
    if not rate_limiter.is_allowed(request.remote_addr or "unknown"):
        return jsonify({"error": "Rate limit exceeded. Please slow down."}), 429

    data = request.get_json(silent=True) or {}
    user_message = sanitize_topic(str(data.get("message", "")).strip())
    if not user_message:
        return jsonify({"error": "Message cannot be empty."}), 400

    cache_key = hashlib.sha256(user_message.lower().encode("utf-8")).hexdigest()
    cached = cache.get(cache_key)
    if cached:
        return jsonify(cached)

    trigger_hardware_state("researching")
    try:
        search_context = topic_specific_search(user_message)
        messages = [
            {"role": "system", "content": JARVIS_SYSTEM_PROMPT},
            {"role": "system", "content": f"Live search results:\n{search_context}"},
            {"role": "user", "content": user_message},
        ]
        trigger_hardware_state("debating")
        reply = ollama_chat(messages)
    finally:
        trigger_hardware_state("complete")

    result = {"reply": reply}
    cache.set(cache_key, result)
    return jsonify(result)

def _tts_cache_key(text: str) -> str:
    return hashlib.sha256(f"{OMNIVOICE_VOICE}:{text}".lower().encode("utf-8")).hexdigest()

def _synthesize_speech(text: str) -> bytes:
    """Get audio bytes for text, using the cache if present. Raises on failure.
    OmniVoice takes ~15-60s to finish booting after _ensure_omnivoice_running()
    launches it, so a freshly-started server routinely refuses the first
    request or two -- retry through that startup window before giving up."""
    cache_key = _tts_cache_key(text)
    cached_audio = tts_cache.get(cache_key)
    if cached_audio:
        return cached_audio

    connect_retries = 10
    for attempt in range(connect_retries):
        try:
            resp = requests.post(
                f"{OMNIVOICE_URL}/audio/speech",
                json={"model": "tts-1", "voice": OMNIVOICE_VOICE, "input": text, "response_format": "wav"},
                timeout=60,
            )
            resp.raise_for_status()
            tts_cache.set(cache_key, resp.content)
            return resp.content
        except requests.exceptions.ConnectionError:
            if attempt == connect_retries - 1:
                raise
            log.info(f"🔊 [OMNIVOICE] Not up yet (attempt {attempt + 1}/{connect_retries}), retrying...")
            time.sleep(5)

@app.route("/tts", methods=["POST"])
def tts():
    if not rate_limiter.is_allowed(request.remote_addr or "unknown"):
        return jsonify({"error": "Rate limit exceeded. Please slow down."}), 429

    data = request.get_json(silent=True) or {}
    text = sanitize_speech_text(str(data.get("text", "")).strip())
    if not text:
        return jsonify({"error": "Text cannot be empty."}), 400

    try:
        audio = _synthesize_speech(text)
    except requests.exceptions.ConnectionError as e:
        log.error(f"❌ OmniVoice still unreachable: {e}")
        return jsonify({"error": "OmniVoice Studio is still starting up. Try again in a few seconds."}), 502
    except Exception as e:
        log.error(f"❌ OmniVoice TTS failed: {e}")
        return jsonify({"error": "Voice synthesis is unavailable. Is OmniVoice Studio running?"}), 502

    return Response(audio, mimetype="audio/wav")

def _warm_boot_greeting_cache():
    """Pre-generate the boot greeting's audio in the background so it's
    already cached by the time a browser actually loads the page, instead of
    the user's first page load being the thing that eats the OmniVoice
    startup + generation wait."""
    try:
        log.info("🔊 [OMNIVOICE] Pre-warming boot greeting audio in the background...")
        _synthesize_speech(BOOT_GREETING)
        log.info("🔊 [OMNIVOICE] Boot greeting cached and ready.")
    except Exception as e:
        log.warning(f"⚠️ [OMNIVOICE] Boot greeting pre-warm failed (will retry on first real request): {e}")

if _should_connect_hardware:
    threading.Thread(target=_warm_boot_greeting_cache, daemon=True).start()

# ── ENTRYPOINT ─────────────────────────────────────────────────
if __name__ == "__main__":
    socketio.run(app, host="0.0.0.0", port=5000, debug=DEBUG_MODE)

Socket.IO lets the server push hardware changes to the dashboard instantly.
Next, the trigger state function sends a letter to the Arduino over USB and tells the dashboard at the same time, so the real and on-screen lights always match.
Then the chat route checks the rate limit, switches to “researching”, gathers web context and asks Ollama for the answer.
Finally, the TTS route passes text to OmniVoice, caches the audio and copes with the voice server still starting up.

A hardware test script

This script checks the wiring without the rest of the app. It cycles through all four states:

"""Standalone Arduino connectivity check -- cycles through every hardware
state so you can confirm wiring/serial without starting the full Flask app.

Usage: python hardware/test_connection.py
"""
import os
import sys
import time

import serial
import serial.tools.list_ports
from dotenv import load_dotenv

load_dotenv(override=True)

STATES = [
    ("0", "IDLE", "Everything off, servo parked at 90 degrees."),
    ("B", "RESEARCHING", "Blue LED (pin 12) should pulse, servo should sweep."),
    ("Y", "DEBATING", "Yellow LED (pin 13) should pulse faster, servo should sweep."),
    ("W", "COMPLETE", "LEDs off, servo should park/stop."),
    ("0", "IDLE", "Back to everything off."),
]

SECONDS_PER_STATE = 4


def find_port() -> str | None:
    env_port = os.getenv("ARDUINO_PORT", "")
    if env_port:
        return env_port

    ports = list(serial.tools.list_ports.comports())
    for p in ports:
        desc = (p.description or "").lower()
        if any(kw in desc for kw in ("arduino", "ch340", "cp210", "usb serial")):
            return p.device

    if ports:
        print("No Arduino-looking device found. Available ports:")
        for p in ports:
            print(f"  {p.device} - {p.description}")
    return None


def main():
    port = find_port()
    if not port:
        print("No serial port found. Is the Arduino plugged in?")
        sys.exit(1)

    print(f"Connecting to {port} ...")
    try:
        conn = serial.Serial(port=port, baudrate=9600, timeout=1)
    except Exception as e:
        print(f"FAILED to open {port}: {e}")
        sys.exit(1)

    time.sleep(2)  # let the board reset after the connection opens
    print(f"Connected on {port}.\n")

    try:
        for signal, name, expectation in STATES:
            print(f"--> Sending '{signal}' ({name}). {expectation}")
            conn.write(signal.encode("utf-8"))
            time.sleep(SECONDS_PER_STATE)
        print("\nDone. If you saw the LEDs/servo react as described, wiring and serial are good.")
    finally:
        conn.close()


if __name__ == "__main__":
    main()

It finds the Arduino’s port by itself, then waits two seconds after connecting, because opening the port restarts the board. Each state lasts four seconds, so you can check the lights, and the port always closes at the end.

The Arduino sketch

// J.A.R.V.I.S. hardware state machine.
// Receives one-character state signals over serial (9600 baud) from app.py's
// trigger_hardware_state() and drives LEDs/servo to match:
//   '0' idle          -> everything off, servo parked/stopped
//   'B' researching    -> blue LED pulses, loading servo sweeps
//   'Y' debating        -> yellow LED pulses (faster), loading servo sweeps
//   'W' complete        -> LEDs off, loading servo parks/stops (work is done)

#include <Servo.h>

const int PIN_RESEARCH_BLUE = 12;
const int PIN_DEBATE_YELLOW = 13;
const int PIN_LOADING_SERVO = 8;

const int SERVO_PARKED_ANGLE = 90;   // "stopped" position
const int SERVO_MIN_ANGLE = 0;
const int SERVO_MAX_ANGLE = 180;
const int SERVO_STEP_DEGREES = 2;
const unsigned long SERVO_STEP_INTERVAL_MS = 15; // lower = faster sweep

Servo loadingServo;

char state = '0';
unsigned long lastLedToggle = 0;
bool pulseOn = false;

unsigned long lastServoStep = 0;
int servoAngle = SERVO_PARKED_ANGLE;
int servoDirection = 1;
bool servoParked = true;

void setLedsOff() {
  digitalWrite(PIN_RESEARCH_BLUE, LOW);
  digitalWrite(PIN_DEBATE_YELLOW, LOW);
}

void parkServo() {
  if (!servoParked) {
    loadingServo.write(SERVO_PARKED_ANGLE);
    servoAngle = SERVO_PARKED_ANGLE;
    servoParked = true;
  }
}

// Continuously sweeps end-to-end while loading, like an old modem's
// activity indicator spinning to show something is happening.
void sweepServo() {
  servoParked = false;
  unsigned long now = millis();
  if (now - lastServoStep < SERVO_STEP_INTERVAL_MS) return;
  lastServoStep = now;

  servoAngle += servoDirection * SERVO_STEP_DEGREES;
  if (servoAngle >= SERVO_MAX_ANGLE) {
    servoAngle = SERVO_MAX_ANGLE;
    servoDirection = -1;
  } else if (servoAngle <= SERVO_MIN_ANGLE) {
    servoAngle = SERVO_MIN_ANGLE;
    servoDirection = 1;
  }
  loadingServo.write(servoAngle);
}

void setup() {
  pinMode(PIN_RESEARCH_BLUE, OUTPUT);
  pinMode(PIN_DEBATE_YELLOW, OUTPUT);
  setLedsOff();

  loadingServo.attach(PIN_LOADING_SERVO);
  loadingServo.write(SERVO_PARKED_ANGLE);

  Serial.begin(9600);
}

void pulse(int pin, unsigned long intervalMs) {
  unsigned long now = millis();
  if (now - lastLedToggle >= intervalMs) {
    pulseOn = !pulseOn;
    lastLedToggle = now;
  }
  digitalWrite(pin, pulseOn ? HIGH : LOW);
}

void loop() {
  if (Serial.available() > 0) {
    char incoming = Serial.read();
    if (incoming == '0' || incoming == 'B' || incoming == 'Y' || incoming == 'W') {
      state = incoming;
      setLedsOff();
      lastLedToggle = millis();
      pulseOn = true;
    }
  }

  switch (state) {
    case 'B':
      pulse(PIN_RESEARCH_BLUE, 400);
      sweepServo();
      break;
    case 'Y':
      pulse(PIN_DEBATE_YELLOW, 200);
      sweepServo();
      break;
    case 'W':
      setLedsOff();
      parkServo();
      break;
    default:
      setLedsOff();
      parkServo();
      break;
  }
}

The pin variables set where each part connects and how far and fast the servo sweeps.
setLedsOff() and parkServo() return everything to a neutral position when a task ends.
The sweep and pulse code uses millis() instead of delay(). As a result, the board keeps listening for commands while the lights and servo move.
setup() sets the pins, attaches the servo to pin 8 and opens serial at 9600 baud.
loop() reads incoming letters and runs the matching lights and movement.

Run and test J.A.R.V.I.S.

Activate the virtual environment and run python app.py.
Watch the log for Connected successfully on COM… and the chosen Ollama model.
Open http://127.0.0.1:5000, and give OmniVoice up to 75 seconds for the greeting.
Send a message. The status should cycle through researching, debating and complete, while the blue LED, yellow LED and servo follow along.
Send the same message again, and the voice should play almost instantly from the cache.

Troubleshooting

The Arduino never connects: check that ARDUINO_PORT matches Device Manager, because the port can change when you switch USB sockets.
The app runs but the lights don’t: Flask’s debug reloader starts the code twice, so the first copy can grab the port. Restart the app fully. Also check the sketch was uploaded, not just verified.
Two voices at once: close extra browser tabs, because each one plays the greeting.
pip fails with SSL errors: antivirus HTTPS scanning (Kaspersky, for example) can cause this. Add an exception for python.exe.
The voice engine runs out of memory: switch OmniVoice to KittenTTS.
Quick health checks: http://localhost:3900/v1/audio/voices for OmniVoice and http://localhost:11434/api/tags for Ollama.

Build the hardware

Here are the parts on the bench:

First, connect the Arduino’s 5V pin to the breadboard’s positive rail and GND to the negative rail. Then join the rails on both sides of the board:

Next, add the two LEDs with a 220Ω resistor each. Their short legs go to the negative rail, the blue LED’s long leg goes to pin 12 and the yellow one to pin 13:

Finally, connect the servo: black to ground, red to 5V and yellow to pin 8:

Project 2: An AI Pomodoro Timer with Arduino

📦 Full project code: AI Pomodoro Manager on GitHub

The second project is a Pomodoro timer on a 4-digit display. When the work session ends, or when you press a button, a CrewAI crew researches a topic and reads a short briefing aloud during your break.

Set up Python

Check that Python 3.12 is installed with py -0p. CrewAI doesn’t support 3.14 yet.
Create a virtual environment in the project folder with Python 3.12, then select it in VS Code with Python: Select Interpreter.
Install the packages: pip install crewai pyserial python-dotenv requests kittentts soundfile.
Then install eSpeak NG, which the voice needs: winget install eSpeak-NG.eSpeak-NG.

Create the crew

In CrewAI, create a new project called “The Hardware-Integrated AI Pomodoro Manager”:

Senior AI Architect: finds the latest technical news about local AI models, agent frameworks and hardware. It ignores marketing and focuses on real changes.
Technical Briefing Writer: turns that research into a short, clear summary for busy developers on a break.

Then add two tasks. The research task looks for 3–5 recent technical updates about {topic}. The summary task condenses them into one paragraph that takes under a minute to read:

Give the architect Brave Search and Tavily, and the writer Brave Search. Both use gpt-4o-mini, and the process is sequential:

Then run it once to test, and publish it to get the API URL and bearer token:

The Pomodoro software

The .env file holds four settings:

CREWAI_CREW_URL= yout crewai url 
CREWAI_CREW_TOKEN=your token 
ARDUINO_PORT=COM9
OMNIVOICE_VOICE=expr-voice-2-m

CREWAI_CREW_URL and CREWAI_CREW_TOKEN connect to your deployed crew, so keep the token private. ARDUINO_PORT is your board’s port, while OMNIVOICE_VOICE picks the voice.

Here is the Arduino sketch:

// --- Pin Definitions ---
// Segments: A, B, C, D, E, F, G, DP
const int segmentPins[8] = {2, 3, 4, 5, 6, 7, 8, 9}; 
// Digits: 1, 2, 3, 4
const int digitPins[4] = {10, 11, 12, 13}; 

const int timerSwitch = A0;   // Starts/Pauses Pomodoro
const int pomodoroLED = A1;   // Solid when working
const int aiStatusLED = A2;   // Pulses/Solid for AI status
const int manualAISwitch = A3; // Forces AI to run

// --- Variables ---
unsigned long previousMillis = 0;
const long interval = 1000; // 1 second update
// Set to 5*60 for the real 5-minute Pomodoro; lowered for fast bench testing.
const int POMODORO_SECONDS = 15;
int minutes = POMODORO_SECONDS / 60;
int seconds = POMODORO_SECONDS % 60;
bool isTimerRunning = false;

// --- AI research status (red LED blinks while Python is still working) ---
bool isResearching = false;
unsigned long lastBlinkMillis = 0;
const long blinkInterval = 250; // ms between blinks while researching
bool blinkState = false;

// 0-9 Segment Truth Table (Common Cathode)
const byte numbers[10][8] = {
  {1,1,1,1,1,1,0,0}, // 0
  {0,1,1,0,0,0,0,0}, // 1
  {1,1,0,1,1,0,1,0}, // 2
  {1,1,1,1,0,0,1,0}, // 3
  {0,1,1,0,0,1,1,0}, // 4
  {1,0,1,1,0,1,1,0}, // 5
  {1,0,1,1,1,1,1,0}, // 6
  {1,1,1,0,0,0,0,0}, // 7
  {1,1,1,1,1,1,1,0}, // 8
  {1,1,1,1,0,1,1,0}  // 9
};

void setup() {
  Serial.begin(9600); // Start serial for Python communication

  for(int i = 0; i < 8; i++) pinMode(segmentPins[i], OUTPUT);
  for(int i = 0; i < 4; i++) pinMode(digitPins[i], OUTPUT);

  pinMode(timerSwitch, INPUT_PULLUP);
  pinMode(manualAISwitch, INPUT_PULLUP);
  pinMode(pomodoroLED, OUTPUT);
  pinMode(aiStatusLED, OUTPUT);
}

void loop() {
  unsigned long currentMillis = millis();

  // 1. Check Timer Switch
  if (digitalRead(timerSwitch) == LOW) {
    delay(200); // Simple debounce
    isTimerRunning = !isTimerRunning;
    digitalWrite(pomodoroLED, isTimerRunning ? HIGH : LOW);
  }

  // 2. Check Manual AI Switch
  if (digitalRead(manualAISwitch) == LOW) {
    delay(200);
    Serial.println("TRIGGER_AI"); // Send signal to Python
    startResearching();
  }

  // 3. Handle Countdown
  if (isTimerRunning && (currentMillis - previousMillis >= interval)) {
    previousMillis = currentMillis;
    if (seconds == 0) {
      if (minutes == 0) {
        // Timer Hit Zero!
        isTimerRunning = false;
        digitalWrite(pomodoroLED, LOW);
        Serial.println("TRIGGER_AI"); // Send signal to Python
        startResearching();
        minutes = POMODORO_SECONDS / 60; // Reset for next time
        seconds = POMODORO_SECONDS % 60;
      } else {
        minutes--;
        seconds = 59;
      }
    } else {
      seconds--;
    }
  }

  // 4. Blink the AI status LED while Python is still working
  if (isResearching && (currentMillis - lastBlinkMillis >= blinkInterval)) {
    lastBlinkMillis = currentMillis;
    blinkState = !blinkState;
    digitalWrite(aiStatusLED, blinkState ? HIGH : LOW);
  }

  // 5. Listen for Python telling us the research is done
  if (Serial.available() > 0) {
    String incoming = Serial.readStringUntil('\n');
    incoming.trim();
    if (incoming == "AI_DONE") {
      isResearching = false;
      digitalWrite(aiStatusLED, LOW);
    }
  }

  // 6. Multiplex the Display
  displayNumber(minutes * 100 + seconds);
}

void displayNumber(int num) {
  int displayDigits[4];
  displayDigits[0] = num / 1000;
  displayDigits[1] = (num / 100) % 10;
  displayDigits[2] = (num / 10) % 10;
  displayDigits[3] = num % 10;

  for (int digit = 0; digit < 4; digit++) {
    // Turn off all digits
    for (int i = 0; i < 4; i++) digitalWrite(digitPins[i], HIGH); 

    // Set segments for current digit
    for (int seg = 0; seg < 8; seg++) {
      digitalWrite(segmentPins[seg], numbers[displayDigits[digit]][seg]);
    }

    // Turn on current digit
    digitalWrite(digitPins[digit], LOW); 
    delay(5); // Wait a tiny bit so the eye sees it
  }
}

void startResearching() {
  // Kicks off the blinking state; the actual blinking happens non-blocking
  // in loop() so the countdown display keeps running smoothly.
  isResearching = true;
  lastBlinkMillis = millis();
  blinkState = true;
  digitalWrite(aiStatusLED, HIGH);
}

It drives the display with 8 segment pins and 4 digit pins. Then it shows each digit very quickly in turn, which is called multiplexing.
The timer switch starts and pauses a 5-minute countdown. When it reaches zero, the board sends TRIGGER_AI to Python and starts blinking the AI LED.
The second button sends TRIGGER_AI at any time.
When Python replies with AI_DONE, the blinking stops.

And the Python side:

import os
import re
import serial
import tempfile
import time
import winsound
import requests
import truststore
from dotenv import load_dotenv

# Use Windows' own certificate trust store instead of certifi's bundled one,
# so HTTPS requests still verify correctly when Kaspersky (or similar AV)
# intercepts TLS traffic with its own locally-trusted root certificate.
truststore.inject_into_ssl()

# KittenTTS needs eSpeak NG's DLL on PATH; point at the default winget install
# location so this works regardless of the shell's own PATH being stale.
_ESPEAK_DIR = r"C:\Program Files\eSpeak NG"
_ESPEAK_DLL = os.path.join(_ESPEAK_DIR, "libespeak-ng.dll")
if os.path.isfile(_ESPEAK_DLL):
    os.environ.setdefault("PHONEMIZER_ESPEAK_LIBRARY", _ESPEAK_DLL)
    if _ESPEAK_DIR not in os.environ.get("PATH", ""):
        os.environ["PATH"] = _ESPEAK_DIR + os.pathsep + os.environ.get("PATH", "")

load_dotenv()

# Reads from .env; update ARDUINO_PORT there to match your exact Arduino port
SERIAL_PORT = os.getenv('ARDUINO_PORT', '/dev/ttyACM0')
BAUD_RATE = 9600

# Deployed CrewAI Enterprise crew (runs in the cloud, no local LLM key needed)
CREW_URL = os.getenv('CREWAI_CREW_URL')
CREW_TOKEN = os.getenv('CREWAI_CREW_TOKEN')
POLL_SECONDS = 2
POLL_TIMEOUT_SECONDS = 300

# Voice used to read the crew's result aloud during the break
OMNIVOICE_VOICE = os.getenv('OMNIVOICE_VOICE', 'expr-voice-2-m')
_tts_model = None


def speak(text):
    global _tts_model
    from kittentts import KittenTTS
    import soundfile as sf

    if _tts_model is None:
        print("Loading voice model...")
        _tts_model = KittenTTS()

    # KittenTTS's nano model fails on long, multi-sentence text (onnxruntime
    # "invalid expand shape" on /bert/Expand), so speak it one sentence at a time.
    sentences = [s.strip() for s in re.split(r'(?<=[.!?])\s+', text) if s.strip()]
    wav_path = os.path.join(tempfile.gettempdir(), "pomodoro_summary.wav")
    for sentence in sentences:
        audio = _tts_model.generate(sentence, voice=OMNIVOICE_VOICE)
        sf.write(wav_path, audio, 24000)
        winsound.PlaySound(wav_path, winsound.SND_FILENAME)


def run_crew(arduino):
    # Tell the Arduino to start blinking the red AI-status LED, and make
    # sure we always tell it to stop, however this run ends up finishing.
    try:
        headers = {
            "Authorization": f"Bearer {CREW_TOKEN}",
            "Content-Type": "application/json",
        }
        inputs = {
            'topic': 'local LLM orchestration frameworks and physical hardware integration'
        }

        response = requests.post(f"{CREW_URL}/kickoff", json={"inputs": inputs}, headers=headers)
        response.raise_for_status()
        kickoff_id = response.json()["kickoff_id"]
        print(f"Crew kicked off (id={kickoff_id}), waiting for it to finish...")

        elapsed = 0
        status = {}
        while elapsed < POLL_TIMEOUT_SECONDS:
            time.sleep(POLL_SECONDS)
            elapsed += POLL_SECONDS

            status_response = requests.get(f"{CREW_URL}/status/{kickoff_id}", headers=headers)
            status_response.raise_for_status()
            status = status_response.json()

            state = str(status.get("state") or status.get("status") or "").upper()
            print(f"Status: {status}")
            if state in ("SUCCESS", "COMPLETED", "FAILED", "ERROR"):
                break
        else:
            print("Timed out waiting for the crew to finish.")
            return

        result = status.get("result") or status.get("output") or status
        print("\nResult:")
        print(result)

        if isinstance(result, str):
            speak(result)
    finally:
        arduino.write(b"AI_DONE\n")


def listen_and_trigger():
    print(f"Connecting to Arduino on {SERIAL_PORT}...")

    try:
        # Establish connection to the Arduino
        arduino = serial.Serial(SERIAL_PORT, BAUD_RATE, timeout=1)
        time.sleep(2)  # Give the Arduino a moment to reset upon connection

        print("Connected! Listening for the Pomodoro timer or manual switch...")

        while True:
            # Check if the Arduino has sent any text
            if arduino.in_waiting > 0:
                raw = arduino.readline()
                message = raw.decode('utf-8', errors='replace').strip()

                if not message:
                    continue

                # Print anything the Arduino sends so wiring/firmware issues
                # are visible instead of silently swallowed.
                if message != "TRIGGER_AI":
                    print(f"[Arduino] {message!r}")
                    continue

                print("\nSignal received! Triggering the AI research crew...")
                run_crew(arduino)
                print("\nResearch complete and summarized!")
                print("Listening for the next trigger...\n")

    except serial.SerialException as e:
        print(f"\nSerial Connection Error: {e}")
        print("Check if the Arduino is plugged in and the SERIAL_PORT in .env is correct.")
    except Exception as e:
        print(f"\nAn unexpected error occurred: {e}")


if __name__ == "__main__":
    listen_and_trigger()

It waits for TRIGGER_AI from the Arduino, then starts the crew through its /kickoff endpoint.
Every 5 seconds it checks /status, for up to 5 minutes, until the crew finishes.
Then it reads the result aloud. It splits the text into sentences first, because the small KittenTTS model struggles with long text.
A finally block always sends AI_DONE, so the LED never gets stuck blinking.

Build the Pomodoro hardware

ComponentQuantityBreadboard1Arduino Uno1USB Cable (for Arduino)14-Digit 7-Segment Display1Jumper Wires (short)24Jumper Wires (long)8Resistors (220Ω or 330Ω)11 (220Ω) or 9 (330Ω)Switches2LEDs2

First, power the breadboard: 5V to the positive rail and GND to the negative rail. If your board has two halves, join their rails too. Then test the power with an LED and resistor before you wire anything else:

Next, connect the LEDs and switches straight to the Arduino: the Pomodoro LED to A1, the AI LED to A2, the timer switch to A0 and the AI button to A3. The firmware uses INPUT_PULLUP, so the switches need no resistors. A 3-pin slide switch connects like this: the left pin to ground, the middle pin to the Arduino and the right pin to 5V.

Wire the 4-digit display

Pin layouts vary between displays, so check your datasheet. On mine, the pins are numbered like this:

   (Top View)
 ________________
|                |
|  12  11  10  9 |
|  |   |   |   | |
|                  |
|   [ 8 8 8 8 ]   |  <-- The 4 digits
|                  |
|  |   |   |   | |
|  1   2   3   4 |
|________________|

Pin NumberConnects ToPin NumberConnects To*1Segment **E**12Digit **2* Common*2Segment **D**11Digit **1* Common*3Segment **DP* (Decimal)10Segment A4Segment C9Segment F5Segment G8Digit 3 Common*6Digit **4* Common*7Segment **B*

In total, the display needs 12 Arduino pins. Each of the 8 segment pins needs a 220Ω resistor, otherwise the segments burn out:

Arduino pinDisplay pinSegment210A37B44C52D61E79F85G93DP (decimal point)

Unlike the segments, the 4 digit pins choose which digit is lit, so they connect directly, without resistors. On a common cathode display, such as a 5461AS, the Arduino turns a digit on by setting its pin LOW:

Arduino Pin–>Display PinDigit*10–>11Digit 1 (Leftmost)11–>12Digit 212–>8Digit 313–>6*Digit 4 (Rightmost)

On a common anode display, such as a 5461BS, it’s the opposite: HIGH turns a digit on. For full brightness you’d add NPN transistors, but a direct connection is fine for testing.

If the numbers look scrambled, your pinout is different. In that case, map it with a coin cell battery: hold one pin to the battery, touch the other pins in turn and note which segment lights. When a whole digit lights up, you’ve found that digit’s common pin.

Where to Take AI Agents with Arduino Next

You’ve now connected AI agents with Arduino hardware twice: once to show what the agents are doing, and once to start them from a physical button. From here, you could add sensors that give the agents real data, or let a finished crew run trigger a motor or a buzzer.

Keep learning: Creating Agents: A Complete Guide · Part 2: Creating AI Agents with Python · How to make AI in Python

What would you connect to an AI agent: an LED, a motor or something else? Tell me in the comments.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.

Why fetch Returns Promise {} in JavaScript

Yunus Emre Güzel — Wed, 14 Oct 2026 13:31:31 +0000

I stared at this exact console output longer than I want to admit: the fetch clearly worked, the response was right there, and my data was still undefined. If that's where you are, here's what's actually happening.
You call an API with fetch, log the result, and get Promise {<pending>} where your data should be. When fetch returns Promise pending, your code isn’t broken. It just didn’t wait.

The Problem: fetch Returns Promise Pending

const data = fetch("https://api.github.com/users/octocat");
console.log(data);   // Promise {<pending>}

You expected a user. You got a strange object with nothing useful in it.

Why It Happens

A request over the internet is slow. It can take half a second, which is a very long time for JavaScript. So fetch doesn’t make your whole page stand still until the answer arrives. It returns immediately and hands you a Promise.

Think of a Promise as a receipt. It isn’t the thing you ordered. It says the thing is on its way. pending means it hasn’t arrived yet. Your console.log ran a few milliseconds after the request left, long before any answer came back.

The Fix: async and await

async function loadUser() {
  const response = await fetch("https://api.github.com/users/octocat");
  const user = await response.json();
  console.log(user.name);   // The Octocat
}

loadUser();

await pauses this one function until the Promise is finished, then gives you the real value. The rest of the page keeps working.

Look closely: there are two awaits. response.json() reads the body of the answer, and that takes time too, so it returns another Promise. Forget the second await and you’re back to pending.

The Same Fix with .then()

fetch("https://api.github.com/users/octocat")
  .then((response) => response.json())
  .then((user) => console.log(user.name));

This is the older style, and it does the same job. Each .then runs when the step before it has finished. Use whichever you find easier to read.

If fetch Still Returns Promise Pending

You returned the data out of the function. const user = loadUser(); is a Promise again, because an async function always returns one. Use the data inside the function, or await the call.
await outside an async function. It works only inside a function marked async, or at the top level of a module script.
A 404 that looks like success. fetch doesn’t throw an error when the server answers “not found”. Check response.ok yourself.

async function loadUser(name) {
  try {
    const response = await fetch("https://api.github.com/users/" + name);
    if (!response.ok) {
      console.log("Request failed:", response.status);
      return;
    }
    const user = await response.json();
    console.log(user.name);
  } catch (error) {
    console.log("Network problem:", error);
  }
}

The try and catch handle the case where there is no connection at all.

So when fetch returns Promise pending, look for the missing await first. MDN’s guide to using the Fetch API covers headers, POST requests and more.

To build a whole page around an API, follow my tutorial on how to make websites using an API. For the basics first, see how to make a website using JavaScript.

Which API are you calling? Tell me in the comments, and paste the line that logs pending if you’re stuck.

Originally published on my blog. I post new C, Python and AI-agent guides there regularly.