Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.pcbcupid.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Z-Claw AI Assistant

Z-Claw is the smallest AI personal assistant you can build. It runs on the GLYPH-C3 board and lets you talk to an AI to control your home, set reminders, and more.

​
How it Works? (The Simple Version)

Even though it’s tiny, your GLYPH-C3 board is doing some smart work:
  1. Connection: It connects to your WiFi and listens for your messages (via Telegram or a Serial monitor).
  2. The Brain: It sends your question to an AI Brain (either running on your computer with Ollama or in the cloud).
  3. Actions: The AI doesn’t just talk—it understands “tools.” For example, if you say “Turn on the light,” the AI tells the board to flick a switch (GPIO pin).
  4. No Lag: Because the code is written in C, it’s extremely fast and uses very little power.

​
What You Need

Before starting, make sure you have your hardware and software environment ready.

​
Hardware Required

  • GLYPH-C3 board (The main AI device).
  • LED (For testing).
  • 220 ohm resistor (For testing).
  • Breadboard (For testing).
  • Jumper wires (For testing).

​
Circuit diagram

Circuit Diagram

​
Software

  • ESP-IDF v5.x: The core development tools from Espressif.
  • Git: Required to download the project files.
  • Python: Required for the build system and provisioning scripts.

​
Software Setup

You have two ways to give your assistant a “brain”:
  1. Ollama (Local): No cost, runs on your own computer (Recommended).
  2. API Key (Cloud): Uses a paid service like OpenRouter.

​
Step 1: Get the Code

First, we need to download the Z-Claw project files from GitHub to your computer. Go to the Z-Claw GitHub Repository and copy the clone URL. GitHub Repo Open your terminal and run: 
git clone --recursive https://github.com/zclaw-org/zclaw.git %userprofile%\ZClaw
Git Clone

​
Step 2: Setup YOUR ESP-IDF Environment

To compile and upload the code, you need the ESP-IDF tools. You have two ways to do this:

​
Option A: ESP-IDF Terminal

If you installed the standalone ESP-IDF 5.x tools, open the ESP-IDF 5.x PowerShell (or CMD) from your Windows Start Menu. Once open, navigate to your project folder: 
cd %userprofile%\ZClaw

​
Option B: VS Code Extension

You can also use the official ESP-IDF extension for VS Code. This makes it easier to build and flash using the VS Code interface.
For a full guide on setting up the extension, see our ESP-IDF Setup Guide.

​
Step 3: Set the Target Board

Every ESP32 chip is slightly different. We need to tell the project that we are using the esp32c3 chip (the one inside your GLYPH-C3). Set Target 
cd ZClaw
idf.py set-target esp32c3

​
Step 4: Configure Your AI Brain

Before connecting your board, you need to decide which AI “Brain” to use. You will need these details for both the configuration menu below and the provisioning script in Step 7.

​
Prepare Your AI Details

  • Option A: Ollama (Local AI): Install Ollama on your computer. Make sure it’s running and keep your computer’s IP address ready (e.g., http://192.168.1.50:11434).
  • Local Device URL: After getting the IP address, you should also have a local device URL ready that you will need to enter in the terminal manually.
  • Option B: OpenRouter (Cloud AI)/OpenAI and keep it ready.
Need an API Key? Get one from OpenRouter or OpenAI by creating a new key named “zclaw”.
OpenRouter Key
Gathering these details now will make the next steps much smoother! You’ll need them again in Step 7.

​
Run the Configuration Menu

Now, open the “Settings” menu to tell your board which AI to talk to: 
idf.py menuconfig
Select zclaw Configuration --->.

​
Step 5: Add Telegram Bot

This allows you to message your assistant from your phone using the Telegram app.
Save your Bot Token and Chat ID; you’ll need them for the provisioning script in Step 7.

​
1. Message @BotFather and use /newbot to get a Token.

​
2. Message @userinfobot to get your Chat ID.

​
Step 6: Build and Flash the Firmware

This command compiles your C code and “burns” the logic onto the ESP32. Run this in your ESP-IDF terminal: 
idf.py build flash
Wait for the process to hit 100% and show “Done.”
Build Project

​
Step 7: Provision Your Credentials

Now, save your WiFi, Telegram, and LLM details into the board’s memory. Run this command in the same terminal: 
"C:\Program Files\Git\bin\bash.exe" scripts/provision.sh --port YOUR_PORT_HERE
(Replace YOUR_PORT_HERE with your actual port number, e.g., COM145). Follow the prompts to enter:
  • WiFi SSID & Password
  • LLM Provider: (e.g., openai or ollama)
  • LLM Model: (e.g., qwen2.5:0.5b)
  • Local Device URL: (e.g., http://192.168.1.50:11434)
  • Telegram Bot Token & Chat ID

​
Step 8: Start the Assistant (Monitor)

Finally, run this to start the assistant and see the output in real-time: 
idf.py -p YOUR_PORT_HERE monitor
Flash Board

​
What can I say?

Try talking to your assistant:
  • “Remind me to water the plants at 8am daily.”
  • “What is the temperature?”
  • “Turn off the lights (GPIO 2).”
Have fun with your mini AI Assistant!