# HERO.Bot

![Build](https://github.com/AugustoSeixasCorretorAvaliador/hero-bot/actions/workflows/build.yml/badge.svg)
![License](https://img.shields.io/github/license/AugustoSeixasCorretorAvaliador/hero-bot)
![Version](https://img.shields.io/badge/version-0.1.0--alpha-blue)

Physical AI Companion for HERO.IA

Website: https://hero.ia.br/hero-bot

Overview
--------

HERO.Bot is an open project to build a physical AI companion that runs the
HeroOS core. This repository contains the HeroOS core, firmware skeletons and
the Desktop Simulator used for development and testing.

Objectives
----------

- Provide a stable HeroOS core that can be validated using the desktop Simulator.
- Keep device-specific drivers separate so hardware swaps are transparent to HeroOS.
- Create a professional, long-term project structure to support team collaboration.

Architecture
------------

- `firmware/` — microcontroller firmware, PlatformIO projects and drivers.
- `hero_os/` — core HeroOS libraries: `HeroEventBus`, `StateMachine`, `AnimationEngine`.
- `simulator/` — Electron-based desktop simulator (development runtime).
- `chrome-extension/` — future Chrome extension components.
- `assets/` — shared assets (animations, images, audio metadata).
- `hardware/` — mechanical and electronics designs.
- `docs/` — design docs, architecture diagrams and manuals.
- `tools/` — helper scripts and dev utilities.

Quick start (Simulator)
-----------------------

```bash
cd hero.bot/firmware/simulator
npm install
npm start
```

Contributing
------------

Please read `CONTRIBUTING.md` before contributing. Follow the commit message
convention and open pull requests against `main`.

License
-------

This project is MIT licensed — see `LICENSE`.
<div align="center">

# 🤖 HERO.BOT  
Ever wanted a **to-do app with a Cute Face**? One that lives on your desk?

**That's HERO.BOT.**

[🛠️ Get started](docs/get_started.md) · [👥 Join the community](https://www.reddit.com/r/deskrobot/) · [📦 Get finished HERO.BOT](https://HERO.BOT.me)


</div>

---

## 🧠 What is HERO.BOT?

**HERO.BOT is a DIY desk robot that helps you work, focus, and learn.**  
It's like a to-do app — but physical, local, and full of personality.

HERO.BOT lives on your desk, connects to your computer, and helps with small daily things like:
- ✅ Managing your to-do list
- ⏲️ Running Pomodoro timers
- 🔔 Setting reminders (like "drink water every 30 mins")
- 😋 Making faces, moving around, and being silly
- 🗣️ Talking to you (coming soon!)

**Think:** a mini Twitch streamer sitting on your desk, cheering you on — but also keeping you on track.


https://github.com/user-attachments/assets/2cbf9e57-a491-4764-b69d-660fd9c50714


## ✨ Made to Be Built

HERO.BOT is open-source and totally customizable.  
You can build it yourself with 3D-printed parts and off-the-shelf components [or just get a finished one](https://www.HERO.BOT.me)

Powered by:
- An ESP32 microcontroller
- A local React dashboard that talks to the robot
- 3D-printed body with custom designs and colors

---

## 🚀 Get Started

Start with the step-by-step guide (WITH A **15 MINUTE VIDEO TUTORIAL**):
- 👉 See: [`docs/get_started.md`](docs/get_started.md)

That guide covers:
- Installing the Dashboard
- Flashing the ESP32 firmware
- Connecting the dashboard to your HERO.BOT
- First run checklist

<!-- 
**📚 Dont know anything about electronics?**  
Go here and get started → [`docs/learning/README.md`](docs/learning/README.md) — This is my mini-roadmap that I did... try learning the same _(not sure if its the best and Im kinda stupid but yea)_
-->
---

## 🗂️ Project Structure

```txt
HERO.BOT/
├── app/                      # React control panel
│
├── firmware/                 # Code that runs on devices
│
├── hardware/                 # Physical build assets (STL files)
│
├── docs/                     # Docs (kept simple for now)
│   ├── get_started.md
│
├── CONTRIBUTING.md
└── README.md
```

---

## 🤝 Contributing

Contributions are welcome, but lets talk first!