XTeInk Tamagotchi

Display your OpenClaw / Clawdbot / MoltBot AI assistant’s activity on a portable e-ink display in real-time using a Clawdbot skill.

---

Table of Contents

1. What is XTeInk Tamagotchi?
2. How It Works (Architecture)
3. Hardware Requirements
4. Software Prerequisites
5. Complete Setup Guide
   • Step 1: Clone the Repository
   • Step 2: Configure and Flash Firmware
   • Step 3: Set Up WiFi
   • Step 4: Install the Clawdbot Skill
   • Step 5: Configure the Skill
   • Step 6: Configure Your Agent to Auto-Run the Skill
   • Step 7: Use the Skill
   • Step 8: Test It
6. Understanding the Components
   • Firmware
   • The Skill
   • MQTT Message Format
7. Customization
   • Custom Sprites
   • Configuration Options
8. Troubleshooting
9. Project Structure
10. FAQ
11. Contributing
12. License
13. Acknowledgments

---

What is XTeInk Tamagotchi?

XTeInk Tamagotchi transforms an XTeInk X4 e-ink display into a companion for your AI assistant. When your OpenClaw/Clawdbot/MoltBot responds to messages, thinks, or works on tasks, the display updates in real-time to show:

Note: This repository does not include sprite images. You will create your own unique character sprites following the workflow in the Custom Sprites section.

---

How It Works (Architecture)

┌─────────────────────────────────────────────────────────────────┐
│                        YOUR COMPUTER                             │
│                                                                 │
│  ┌──────────────┐     ┌──────────────────┐     ┌─────────────┐  │
│  │  Clawdbot    │────▶│   Clawdbot       │────▶│ mosquitto_pub│  │
│  │  (main app)  │     │   Skill          │     │  (MQTT CLI)  │  │
│  │              │     │   (manual)       │     │              │  │
│  └──────────────┘     └──────────────────┘     └──────┬──────┘  │
│                                                        │         │
│                                                        │ MQTT    │
│                                                        ▼         │
│                                                broker.hivemq.com │
│                                                         │         │
└────────────────────────────────────────────────────────┼─────────┘
                                                         │
                              ┌──────────────────────────┼──────────┐
                              │                          │          │
                              ▼                          ▼          │
                    ┌─────────────────┐        ┌─────────────────┐  │
                    │   XTeInk X4     │        │   Other Users   │  │
                    │   (Display)     │        │   (Same topic)  │  │
                    │   ESP32-C3      │◀───────│   can subscribe │  │
                    │   Subscribes    │        │                 │  │
                    └─────────────────┘        └─────────────────┘  │

Data Flow

1. Clawdbot processes a user message and generates a response
2. You send the response to Telegram (or your messaging platform)
3. You run the skill (xteink-display skill) with your message and state
4. mosquitto_pub publishes a JSON message to the MQTT broker
5. The XTeInk (subscribed to the same topic) receives the message
6. The firmware parses the JSON and updates the e-ink display

The skill approach gives you:

• ✅ Full control over when/what is displayed
• ✅ Works with any messaging platform (Telegram, Discord, Signal, etc.)
• ✅ No automatic publishing of sensitive/thought messages
• ✅ Can customize state (thinking, talking, excited, etc.) per message

---

Hardware Requirements

Where to buy: AliExpress (affiliate link) | XTeInk Store

No Raspberry Pi, no additional batteries, no soldering required. The XTeInk X4 is a complete, self-contained device.

---

Software Prerequisites

Required Tools

# 1. PlatformIO CLI (for building and flashing firmware)
# Install via pip:
pip install platformio

# 2. MQTT client tools (for the skill to publish messages)
# macOS:
brew install mosquitto

# Linux (Debian/Ubuntu):
sudo apt install mosquitto-clients

# 3. Git (for cloning the repository)
# Already installed on most systems

Verify Installation

# Check PlatformIO
pio --version

# Check MQTT client
which mosquitto_pub

# Check Git
git --version

---

Complete Setup Guide

Step 1: Clone the Repository

git clone https://github.com/maddiedreese/xteink-tamagotchi.git
cd xteink-tamagotchi

Step 2: Configure and Flash Firmware

2.1 Edit the Configuration

Open firmware/src/main.cpp and modify the MQTT topic:

// Around line 20-25
const char* MQTT_SERVER = "broker.hivemq.com";
const int MQTT_PORT = 1883;

// CHANGE THIS to something unique for your setup!
const char* MQTT_TOPIC = "tamagotchi/your-unique-id/display";

Choose a unique topic to avoid conflicts with other users. Examples:

• tamagotchi/alice-macbook/display
• tamagotchi/myname-2024/display
• tamagotchi/random123xyz/display

2.2 Connect the XTeInk

1. Connect your XTeInk X4 to your computer via USB-C
2. The device should appear as a serial device (e.g., /dev/ttyUSB0 on Linux or /dev/cu.usbserial-xxx on macOS)

2.3 Build and Flash

cd firmware
pio run -t upload

This will:

1. Download required libraries
2. Compile the firmware
3. Flash it to the XTeInk X4

---

Step 3: Set Up WiFi

After flashing, the XTeInk will create a WiFi network called “Tamagotchi-Setup”.

1. Connect to this network from your phone or computer
2. A captive portal should appear automatically. If not, open a browser and navigate to http://192.168.4.1
3. Select your WiFi network from the list
4. Enter your WiFi password
5. Click “Save”

The device will reboot and connect to your WiFi. The display should show:

• “WiFi: OK” in the bottom status bar
• “MQTT: OK” once connected to the broker

Note: The WiFi setup portal will automatically start every 3 minutes if WiFi connection is lost.

---

Step 4: Install the Clawdbot Skill

The skill is a Clawdbot plugin that lets you manually publish messages to the e-ink display. Copy it to your skills directory:

# Copy the skill to your Clawdbot skills folder
mkdir -p ~/.clawdbot/skills
cp -r /path/to/xteink-tamagotchi/skill ~/.clawdbot/skills/xteink-display

# Or if using the main repo's skill location:
cp -r skill ~/.clawdbot/skills/xteink-display

The skill is now installed! You can verify it by checking:

ls ~/.clawdbot/skills/xteink-display/
# Should show: SKILL.md  script.sh

---

Step 5: Configure the Skill

The skill needs your MQTT topic configuration. You can configure it in the skill’s SKILL.md or pass parameters directly:

Option A: Edit SKILL.md

Open ~/.clawdbot/skills/xteink-display/SKILL.md and update the metadata:

metadata: 
  clawdbot:
    config:
      properties:
        mqtt_broker:
          default: broker.hivemq.com
          type: string
        mqtt_topic:
          default: tamagotchi/your-unique-id/display
          type: string
      required:
        - mqtt_broker
        - mqtt_topic
      type: object

Option B: Use Default Topic

The skill defaults to tamagotchi/default/display. To use a custom topic, edit the script:

# Open the script
nano ~/.clawdbot/skills/xteink-display/script.sh

# Change the topic variable:
TOPIC="tamagotchi/your-unique-id/display"

Important: Use the same topic you configured in the firmware!

---

Step 7: Use the Skill

After sending a message to your AI assistant on Telegram (or any platform), run the skill to update the display:

# Navigate to the skill directory
cd ~/.clawdbot/skills/xteink-display

# Run the script with your message and state
./script.sh "Your message here" talking

# Examples for different states:
./script.sh "" idle
./script.sh "New message received!" alert
./script.sh "Processing your request..." thinking
./script.sh "Searching the web..." working
./script.sh "Task completed!" excited
./script.sh "Something went wrong" error

Available States

---

Step 6: Configure Your Agent to Auto-Run the Skill

Important: You need to configure your Clawdbot agent to run the skill after every outgoing message. This ensures the display updates automatically when you respond to users.

Option A: Add to Agent’s Instructions (Recommended)

Add this to your agent’s SOUL.md or AGENTS.md:

## XTeInk Display

After every message you send to users (on Telegram, Discord, Signal, etc.), immediately run the XTeInk skill:

```bash
cd ~/.clawdbot/skills/xteink-display && ./script.sh "Your exact message here" talking

States to use:

• idle - default state
• alert - new message received from user
• thinking - processing/thinking
• talking - responding to user
• working - using a tool (search, fetch, etc.)
• excited - task completed successfully
• error - error at some point in the process
• sleeping - idle for 5+ minutes

Pass the exact same message you sent to the user.

#### Option B: Add to Daily Notes Template

If you use daily notes or templates, add a reminder to run the skill after each response.

---

### Step 8: Test It

1. **Start Clawdbot:**
   ```bash
   clawdbot

2. Send a message to your AI assistant

3. After responding, run the skill:

   cd ~/.clawdbot/skills/xteink-display
   ./script.sh "Your response here" talking
   

4. Watch your XTeInk display — it should:

   • Show the “talking” sprite
   • Display your message
   • Show “Responding…” as the activity

---

Understanding the Components

Firmware

The firmware (firmware/src/main.cpp) runs on the ESP32-C3 and:

Key Configuration (in firmware/src/main.cpp):

const char* MQTT_SERVER = "broker.hivemq.com";  // MQTT broker
const int MQTT_PORT = 1883;                      // MQTT port
const char* MQTT_TOPIC = "tamagotchi/demo/display"; // Your topic
const char* AP_NAME = "Tamagotchi-Setup";        // WiFi setup AP name

---

The Skill

The skill (skill/script.sh) is a Clawdbot skill that you manually invoke to publish messages to the e-ink display.

How to use:

./script.sh "Your message" talking

What it does:

1. Receives your message and state as command-line arguments
2. Builds the JSON payload (message, state, activity)
3. Publishes to MQTT using mosquitto_pub
4. Updates the e-ink display with your message and current state

Key features:

• Manual control - you decide when/what to publish
• Works with any messaging platform (Telegram, Discord, Signal, etc.)
• No automatic publishing of sensitive content
• Full control over states (alert, thinking, talking, excited, error, idle, sleeping)

Configuration (in skill/script.sh):

BROKER="broker.hivemq.com"       # MQTT broker
TOPIC="tamagotchi/demo/display"  # Your unique topic
MAX_CHARS=288                    # Max message length (display limit)

---

MQTT Message Format

The skill publishes JSON messages in this format:

{
  "message": "The text to display (up to 288 chars)",
  "state": "talking",
  "activity": "Responding..."
}

Valid State Values

---

Customization

Custom Sprites

You can replace the default sprites with your own designs. Here’s our actual workflow:

Our Sprite Creation Workflow

1. Generate with Nano Banana Pro

   • Use Gemini 3 Pro Image (Nano Banana Pro) to generate the initial sprite design
   • Get a clean PNG with your character/design

2. Remove Background with Canva Pro

   • Upload to Canva
   • Use “Remove Background” tool to get a clean transparent background
   • Export as PNG

3. Convert to Pixel Art with Piskel

   • Import the PNG into Piskel (piskelapp.com)
   • Resize to 200×200 pixels
   • Use the pixel art tools to clean up and stylize
   • Export as PNG

4. Run the Converter

   # Install dependencies first
   pip install platformio
   python3 convert_sprites.py
   

5. Copy Generated Headers

   cp ~/clawdbot-tamagotchi/xteink-firmware/include/*.h firmware/include/
   

6. Rebuild and Flash

   cd firmware
   pio run -t upload
   

Sprite Requirements

Sprite Names

sprites/
├── sleeping.png
├── idle.png
├── alert.png
├── thinking.png
├── talking.png
├── working.png
├── excited.png
└── error.png

---

Configuration Options

Firmware (firmware/src/main.cpp)

Skill (script.sh Configuration)

---

Troubleshooting

Display stuck on “Starting…”

Cause: WiFi captive portal is waiting for configuration.

Solution:

1. Connect to “Tamagotchi-Setup” WiFi network
2. Follow the setup wizard to enter your WiFi credentials

---

Display shows “WiFi: --”

Cause: WiFi connection was lost.

Solution:

1. The device will create a setup portal every 3 minutes
2. Connect to “Tamagotchi-Setup” and reconfigure WiFi
3. Or wait for the auto-reconnect attempt

---

Display shows “MQTT: --”

Cause: Cannot connect to MQTT broker.

Solution:

1. Check your internet connection
2. Verify the MQTT broker is online (broker.hivemq.com is a public broker)
3. The device will auto-reconnect every 5 seconds

---

Skill not working

Checklist:

1. Verify mosquitto_pub is installed:

   which mosquitto_pub
   

2. Check the topic matches:

   • Firmware topic: firmware/src/main.cpp → MQTT_TOPIC
   • Skill topic: skill/script.sh → TOPIC

3. Test manually:

   mosquitto_pub -h broker.hivemq.com -t "tamagotchi/test/display" \
     -m '{"message":"Hello!","state":"talking","activity":"Testing"}'
   

4. Check the skill script is executable:

   chmod +x skill/script.sh
   

5. Run with verbose output:

   cd skill
   ./script.sh "Test message" talking
   

---

Messages are truncated

Cause: Maximum message length is 288 characters (display limitation).

Solution: The skill automatically truncates messages. Longer messages will end with “…” on the display.

---

Display doesn’t update

Solution:

1. Check the display isn’t in “sleeping” mode (wait or send a message)
2. Verify WiFi and MQTT show “OK” in the status bar
3. Press the reset button on the XTeInk

---

Project Structure

xteink-tamagotchi/
├── firmware/                    # ESP32 PlatformIO project
│   ├── src/
│   │   └── main.cpp            # Main firmware (C++)
│   ├── include/
│   │   ├── sprites.h           # (Auto-generated - see sprites/ folder)
│   │   ├── sprite_*.h          # (Auto-generated - see sprites/ folder)
│   │   └── FreeMonoBold*.h     # Font files
│   └── platformio.ini          # PlatformIO configuration
│
├── skill/                       # Clawdbot skill for publishing to display
│   ├── SKILL.md                # Skill metadata and configuration
│   └── script.sh               # Shell script for publishing to MQTT
│
├── sprites/                     # Your sprite templates (create your own!)
│   ├── README.md               # Sprite creation guide
│   ├── sleeping.png            # (add your sprite here)
│   ├── idle.png                # (add your sprite here)
│   ├── alert.png               # (add your sprite here)
│   ├── thinking.png            # (add your sprite here)
│   ├── talking.png             # (add your sprite here)
│   ├── working.png             # (add your sprite here)
│   ├── excited.png             # (add your sprite here)
│   └── error.png               # (add your sprite here)
│
├── convert_sprites.py           # PNG → C header converter
├── README.md                    # This file
├── CONTRIBUTING.md              # Contribution guidelines
├── CODE_OF_CONDUCT.md           # Community standards
└── LICENSE                      # MIT License

Important: The firmware/include/ and sprite PNG files are not included. You must create your own sprites following the Custom Sprites guide.

---

FAQ

Can I use a different MQTT broker?

Yes! Change both:

1. Firmware (firmware/src/main.cpp):

   const char* MQTT_SERVER = "your-broker.com";
   

2. Skill (environment variable):

   export CLAWDBOT_XTEINK_BROKER="your-broker.com"
   

   Or edit skill/script.sh:

   MQTT_BROKER="your-broker.com"
   

---

Can I run the XTeInk without Clawdbot?

Yes! The XTeInk is just an MQTT subscriber. You can publish messages from any source:

mosquitto_pub -h broker.hivemq.com -t "tamagotchi/your-topic/display" \
  -m '{"message":"Hello!","state":"talking","activity":"Testing"}'

---

How long does the battery last?

The XTeInk X4 has a built-in battery. With typical usage (a few messages per day), expect several days of operation. The display only consumes power when refreshing.

---

Can I use this with other AI assistants?

Yes! The display works with any AI assistant that can publish MQTT messages. You’ll need to:

1. Create a custom integration for your assistant
2. Publish JSON in the correct format
3. Subscribe to the same topic

---

Contributing

Contributions are welcome! Here are some ways you can help:

• Bug reports — Found an issue? Open an issue!
• Feature requests — Have an idea? Let us know!
• Pull requests — Fix a bug or add a feature
• Documentation — Improve this README or add examples

Please read CONTRIBUTING.md for details.

---

License

This project is licensed under the MIT License.

See the LICENSE file for full details.

---

Acknowledgments

• OpenClaw Team — For the amazing AI assistant framework
• Clawdbot Community — For inspiration and feedback
• ZinggJM — For the GxEPD2 e-ink library
• HiveMQ — For the free public MQTT broker
• XTeInk — For the excellent hardware

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with 🫡 for the OpenClaw/Clawdbot community