Jarvis: Desk Buddy

An open-source desk buddy that blinks, tells the time, and notices when you're near.

Overview

Jarvis is an open-source desktop companion built on an ESP32. It shows a pair of animated eyes on an OLED display, keeps the time synced over Wi-Fi, and uses an ultrasonic sensor to notice when you get close, looking up and reacting when you're near.

Timekeeping is handled over the network: the ESP32 connects to Wi-Fi and syncs to an NTP server on boot, with automatic daylight-saving handling for the local timezone, so there's no dedicated RTC to keep set. The eyes are hand-drawn with the U8g2 library, blinking, glancing around, and shifting between moods, and two buttons let you switch between views.

The project is designed to be:

• Expressive, with animated eyes that blink, glance around, and react to presence.
• Easy to read, with a crisp OLED display and a WiFi-synced clock.
• Simple to build, on a single USB-C-powered board.
• Hackable and well-documented, as a learning reference for embedded projects.

Pinout

The table below maps each component to its ESP32 GPIO. For the full wiring, the complete schematic is available as a PDF, and the entire KiCad project is included too, with the BOM and component details across several distributors.

Component	Component Pin	ESP32 GPIO	Notes
OLED Display (SSD1306, I²C)	VCC	3V3	Do not use 5V / VIN
	GND	GND	Common ground
	SDA	GPIO19	I²C data
	SCL	GPIO20	I²C clock
Next Screen Button	Pin 1	GPIO4	INPUT_PULLUP; pressed = LOW
	Pin 2	GND	Other leg to ground
Previous Screen Button	Pin 1	GPIO5	INPUT_PULLUP; pressed = LOW
	Pin 2	GND	Other leg to ground

---

Getting Started

Prerequisites

• PlatformIO (VS Code extension or CLI).
• An ESP32 board, an SSD1306 OLED and two push buttons (or just the Wokwi simulator, see below).

Configuration

Wi-Fi and API credentials are kept out of version control. Copy the template and fill in your own:

cp secrets.h.example secrets.h

Then edit secrets.h with your network details:

#define WIFI_SSID "your_wifi"
#define WIFI_PASS "your_password"
#define WEATHER_API_KEY "your_openweather_api_key"

The weather screen uses the OpenWeather API. Create a free account to get an API key and drop it in secrets.h.

Build & Flash

pio run              # compile
pio run -t upload    # flash to the board
pio device monitor   # open the serial monitor

Run in the simulator (no hardware needed)

You can run Jarvis entirely in VS Code without any physical hardware using the Wokwi simulator.

1. Install the Wokwi Simulator extension for VS Code.

2. Create a wokwi.toml file in the project root with the following content:

     [wokwi]
     version = 1
     firmware = ".pio/build/jarvis/firmware.bin"
     elf = ".pio/build/jarvis/firmware.elf"

3. Add a diagram.json in the project root describing the circuit. You can copy it from the public Wokwi project here: wokwi.com/projects/469374163665964033.

4. Set your credentials to Wokwi's guest network in secrets.h:

   #define WIFI_SSID "Wokwi-GUEST"
   #define WIFI_PASS ""

5. Build the firmware with pio run, then open diagram.json and start the simulator.

---

License

Copyright © 2026 Carmen

Jarvis is open-source and released under the MIT License.

See LICENSE.md for the full details.

Credits & Team

Built and maintained by Carmen :)