{"id":47754238,"url":"https://github.com/jovinull/bixim","last_synced_at":"2026-04-03T04:01:56.292Z","repository":{"id":348143593,"uuid":"1196664615","full_name":"Jovinull/Bixim","owner":"Jovinull","description":"Cross-platform virtual pet engine for ESP32 + PC. HAL architecture, fixed-timestep game loop, FSM pet logic, and SSD1306 OLED rendering — built from scratch in C/C++.","archived":false,"fork":false,"pushed_at":"2026-03-31T00:12:12.000Z","size":80,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T03:14:17.668Z","etag":null,"topics":["cpp","cross-platform","embedded","embedded-systems","esp32","finite-state-machine","game-engine","iot","oled","platformio","raylib","retro","ssd1306","tamagotchi","virtual-pet"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jovinull.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T23:22:23.000Z","updated_at":"2026-03-31T00:14:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Jovinull/Bixim","commit_stats":null,"previous_names":["jovinull/bixim"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Jovinull/Bixim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jovinull%2FBixim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jovinull%2FBixim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jovinull%2FBixim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jovinull%2FBixim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jovinull","download_url":"https://codeload.github.com/Jovinull/Bixim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jovinull%2FBixim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31333229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T03:20:36.090Z","status":"ssl_error","status_checked_at":"2026-04-03T03:20:35.133Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","cross-platform","embedded","embedded-systems","esp32","finite-state-machine","game-engine","iot","oled","platformio","raylib","retro","ssd1306","tamagotchi","virtual-pet"],"created_at":"2026-04-03T04:01:21.221Z","updated_at":"2026-04-03T04:01:56.270Z","avatar_url":"https://github.com/Jovinull.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bixim: ESP32-Based Virtual Pet Embedded System\n\n[English](README.md) | [Português](README.pt-br.md)\n\n## Project Overview\nThe **Bixim** project (provisional/code name) is a complete implementation (hardware and software) of a portable digital entertainment device, inspired by the classic virtual pet architecture of 1996.\n\nUnlike traditional emulators that rely on proprietary ROM dumps, this project uses a **High-Level Emulation (HLE) and Custom Logic** approach. This ensures total independence from third-party intellectual property, resulting in a 100% original work that demonstrates proficiency in reverse engineering concepts, embedded systems development, and hardware design.\n\n## Software Architecture and Technology Choice\n\nThe system core was developed entirely in **C/C++17**. The choice of this language is justified by the following factors:\n\n1. **Memory Management and Performance:** Bare-metal or RTOS-based development on the ESP32 requires strict control over memory allocation and CPU cycles. C/C++ provides the granularity needed to ensure a stable frame rate (FPS) on the OLED display, without the bottlenecks of interpreted languages.\n2. **Energy Efficiency:** Natively compiled code minimizes processor active time, allowing for more efficient use of ESP32 *deep sleep* strategies, which is critical for a device powered by a small LiPo battery.\n3. **Hardware Interaction:** Direct manipulation of registers, interrupts (ISRs) for button reading, and pulse-width modulation (PWM) control for the buzzer are implemented with maximum efficiency using native C/C++ libraries.\n\n### Software Architecture: HAL and Game Loop\n\nThe project implements a modern game engine architecture designed for deterministic behavior and portability:\n\n* **Hardware Abstraction Layer (HAL):** Key interfaces (`IDisplay`, `ITimer`) allow the same logic code to run unmodified on both Windows (using Raylib for simulation) and ESP32 (using SSD1306 OLED drivers via I2C).\n* **Game Loop Architecture:** Uses a **Fixed Timestep Accumulator**. This decouples logic (running at a fixed 10 Hz) from rendering (targeting 30 FPS), ensuring consistent simulation speed regardless of CPU variance or display refreshrate.\n* **State Logic (Custom Game Engine):** The internal engine implements a finite state machine (FSM) that simulates the system's organic cycle:\n    * **Life Module:** Manages temporal decay variables (Hunger, Sleep, Happiness, Age).\n    * **Rendering Module:** A custom **FrameBuffer** class manages the 128x64 monochromatic bit matrix, optimized for I2C transfers.\n    * **Interrupt Module:** Handles hardware/software debouncing of physical buttons.\n\n## Hardware Specifications (Bill of Materials - BOM)\n\nThe physical project was designed to be modular during the prototyping phase (breadboard) and highly miniaturized for the production version.\n\n* **Microcontroller: ESP32 (WROOM or C3)**\n    * Responsible for central processing. The ESP32 allows for future Over-The-Air (OTA) updates and wireless communication via Wi-Fi/Bluetooth (ESP-NOW).\n* **Display: 0.96\" OLED Module (SSD1306 Controller)**\n    * High-contrast, ultra-low power monochromatic video interface. Communication via I2C protocol (SDA/SCL), using only two data pins from the microcontroller.\n* **Audio: Passive Piezoelectric Buzzer**\n    * Unlike active buzzers, the passive version allows for square wave synthesis via PWM at different frequencies, enabling faithful recreation of 8-bit soundtracks and dynamic sound feedback.\n* **Input Interface: Tactile Switches (6x6x4.3mm Push Buttons)**\n    * Three strategically placed buttons for menu navigation (Select, Confirm, Cancel), with internal pull-up resistors activated on the microcontroller.\n* **Power \u0026 Battery Management System:**\n    * **Battery:** 3.7V LiPo cell (approx. 300mAh - 500mAh).\n    * **Charging Module:** TP4056 board with USB-C interface for safe lithium cell charging.\n    * **Slide Switch:** Hardware-level power cut control.\n\n## Physical Design and Assembly\n\nThe project's evolution includes the transition from a breadboard circuit to a portable final product. The casing was designed considering ergonomics and the space constraints of electronic components.\n\nThe physical prototyping and manufacturing of the final case can be done through digital fabrication techniques such as 3D printing (leveraging printing services and maker spaces available in Aracaju and the region) or through *retrofitting* techniques, adapting the internal circuit to obsolete classic device casings.\n\n## Roadmap and Future Features\n\n- [x] Prototyping state logic and rendering on the OLED matrix (Fixed Timestep \u0026 HAL implemented).\n- [x] Implementation of hardware-abstracted input system and debouncing (IInput HAL).\n- [x] Implementation of Pet FSM, statistics decay system, and HUD rendering.\n- [ ] Implementation of audio system (Buzzer PWM).\n- [ ] Energy consumption optimization (ESP32 Sleep Modes).\n- [ ] Integration of final hardware into the case.\n- [ ] **Multiplayer via ESP-NOW:** Implementation of low-latency peer-to-peer communication for interaction between two nearby physical devices.\n- [ ] **Educational Integration:** Implementation of advanced custom animations, including an experimental module for the pet to teach basic sign language (Libras) to the user.\n\n## Development Environment Setup (Getting Started)\n\nThis section covers the complete setup for a clean Windows machine. Follow each step in the order indicated.\n\n### Prerequisites Overview\n\n| Tool | Purpose |\n|---|---|\n| VS Code | IDE |\n| PlatformIO IDE Extension | Build system, library manager, uploader |\n| MSYS2 + MinGW-w64 | C++ compiler toolchain for the `native` (PC) build |\n| Raylib (via MSYS2) | Graphics library for the debug build on PC |\n\n---\n\n### Step 1 — Install VS Code\n\n1. Go to **code.visualstudio.com** and download the **Windows x64** installer.\n2. Run the installer. During setup, check **\"Add to PATH\"** and **\"Register Code as an editor for supported file types\"**.\n3. Verify the installation by opening a new terminal (`Win + R` -\u003e `cmd`) and running:\n   ```\n   code --version\n   ```\n   It should display a version number (e.g., `1.89.x`).\n\n---\n\n### Step 2 — Install VS Code Extensions\n\nThis repository includes a `.vscode/extensions.json` file with all required extensions listed. When you open the project folder in VS Code for the first time, a popup will automatically appear asking if you want to install the recommended extensions. Click **\"Install All\"**.\n\nIf the popup does not appear, install them manually via `Ctrl + Shift + X`. The required extensions and their exact IDs are:\n\n| Extension | Publisher | ID |\n|---|---|---|\n| PlatformIO IDE | PlatformIO | `platformio.platformio-ide` |\n| C/C++ | Microsoft | `ms-vscode.cpptools` |\n| C/C++ Extension Pack | Microsoft | `ms-vscode.cpptools-extension-pack` |\n| C/C++ Themes | Microsoft | `ms-vscode.cpptools-themes` |\n| CMake Tools | Microsoft | `ms-vscode.cmake-tools` |\n| Makefile Tools | Microsoft | `ms-vscode.makefile-tools` |\n| clangd | LLVM | `llvm-vs-code-extensions.vscode-clangd` |\n\n\u003e **WARNING — PlatformIO:** There are third-party extensions with similar names published by unofficial authors. Install **only** the extension with ID `platformio.platformio-ide` (publisher: **PlatformIO**). Any other will fail to install PlatformIO Core and the `pio` command will not be available. Always check the extension ID before clicking Install.\n\nAfter installing PlatformIO IDE, VS Code will reload. A PlatformIO icon (alien head) should appear in the left sidebar. Click it and wait for the home screen to load.\n\n\u003e **Note:** PlatformIO manages its own Python environment internally. There is no need to install Python separately.\n\n---\n\n### Step 2.5 — Add PlatformIO CLI (`pio`) to System PATH\n\nThe PlatformIO extension installs the `pio` executable in a local user folder that is **not** automatically added to the system PATH. Without this step, running `pio` in PowerShell or Command Prompt will fail with \"command not recognized\", even if the extension works inside VS Code.\n\n**Verify if the executable exists:**\n```powershell\nTest-Path \"C:\\Users\\$env:USERNAME\\.platformio\\penv\\Scripts\\pio.exe\"\n```\nIf it returns `True`, proceed. If it returns `False`, open VS Code, wait for PlatformIO to finish initial configuration (progress bar in the bottom status bar), and check again.\n\n**Add to system PATH:**\n1. Open **Start** -\u003e search for **\"Edit the system environment variables\"**.\n2. Click **\"Environment Variables...\"**.\n3. Under **System variables**, select `Path` -\u003e click **Edit** -\u003e click **New**.\n4. Add the path below (replace `felip` with your Windows username):\n   ```\n   C:\\Users\\felip\\.platformio\\penv\\Scripts\n   ```\n5. Click **OK** on all dialogs.\n\n**Open a new PowerShell window** (PATH changes only apply to new terminals) and verify:\n```\npio --version\n```\nExpected output: `PlatformIO Core, version 6.x.x`\n\n\u003e **Note:** `pio` commands can also be run from the integrated VS Code terminal (`Ctrl + ` `) without this PATH change, as VS Code configures its own terminal environment. The PATH step is only necessary for running `pio` in standalone PowerShell or Command Prompt windows.\n\n---\n\n### Step 3 — Install MSYS2 and the MinGW-w64 Toolchain\n\nMSYS2 provides the GCC/G++ compiler needed to build and run the `native` (PC) environment.\n\n1. Go to **msys2.org** and download the installer (`msys2-x86_64-YYYYMMDD.exe`).\n2. Run the installer. Accept the default installation path: `C:\\msys64`.\n3. After installation, open the **\"MSYS2 MINGW64\"** shell (not MSYS2 MSYS).\n4. Update the package database:\n   ```bash\n   pacman -Syu\n   ```\n   The terminal will close automatically. Reopen the MINGW64 shell and run:\n   ```bash\n   pacman -Su\n   ```\n5. Install the MinGW-w64 GCC toolchain:\n   ```bash\n   pacman -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb make\n   ```\n6. Add MinGW-w64 to the Windows system PATH:\n   - Open **Start** -\u003e search for **\"Edit the system environment variables\"**.\n   - Click **\"Environment Variables...\"**.\n   - Under **System variables**, select `Path` and click **Edit**.\n   - Click **New** and add: `C:\\msys64\\mingw64\\bin`\n   - Click **OK** on all dialogs.\n7. Verify in a **new** Command Prompt or PowerShell window:\n   ```\n   g++ --version\n   ```\n   Expected output: `g++.exe (Rev..., Built by MSYS2 project) 14.x.x`\n\n---\n\n### Step 4 — Install Raylib via MSYS2\n\nRaylib is the graphics library used by the `native` build to simulate the OLED display on the PC.\n\n1. Open the **MSYS2 MINGW64** shell.\n2. Run:\n   ```bash\n   pacman -S mingw-w64-x86_64-raylib\n   ```\n3. Verify the installation:\n   ```bash\n   ls /mingw64/include/raylib.h\n   ls /mingw64/lib/libraylib.a\n   ```\n   Both files should exist. If they do, Raylib is ready. This repository's `platformio.ini` is already pre-configured to find these paths at `C:/msys64/mingw64/`.\n\n---\n\n### Step 5 — Clone the Repository and Open in VS Code\n\n```bash\ngit clone https://github.com/jovinull/bixim.git\ncd bixim\ncode .\n```\n\nVS Code will open the project. PlatformIO will detect `platformio.ini` and index the project automatically (may take 1-2 minutes on first opening).\n\n---\n\n### Step 6 — Build and Execution: Native Environment (PC)\n\nThe `native` environment compiles the project as a standard Windows executable using Raylib for rendering. Use this target for all logic development and debugging before flashing to hardware.\n\n**Via VS Code:**\n- Click the PlatformIO icon in the sidebar.\n- Under **Project Tasks -\u003e native**, click **Build** and then **Upload and Monitor** (which executes the binary).\n\n**Via terminal (in project root):**\n```bash\n# Just compile\npio run -e native\n\n# Compile and execute the binary\npio run -e native -t exec\n```\n\nA window titled **\"Bixim - Native Debug Build\"** should open.\n\n---\n\n### Step 7 — Build and Flash: ESP32 Environment\n\n1. Connect your ESP32 board via USB.\n2. Identify the COM port: open **Device Manager** (`Win + X` -\u003e Device Manager) -\u003e expand **Ports (COM and LPT)** -\u003e note the port (e.g., `COM3`).\n3. In VS Code, PlatformIO detects the port automatically. If not detected, add `upload_port = COMX` to the `[env:esp32dev]` section in `platformio.ini`.\n\n**Via VS Code:**\n- Under **Project Tasks -\u003e esp32dev**, click **Upload**.\n\n**Via terminal:**\n```bash\n# Compile and flash\npio run -e esp32dev -t upload\n\n# Open serial monitor (115200 baud) after flashing\npio device monitor\n```\n\nExpected serial output:\n```\n[Bixim] Booting...\n[Bixim] Display OK. Boot complete.\n```\n\n---\n\n### Project Directory Structure\n\n```\nbixim/\n├── platformio.ini      # Build system configuration (all environments)\n├── src/\n│   └── main.cpp        # Unified entry point with #ifdef guards per platform\n├── include/            # Shared header files (.h / .hpp)\n├── lib/                # Local libraries (project-specific, not from registry)\n├── hardware/           # Schematics, KiCad files, BOM\n├── docs/               # Technical milestones and architecture documentation\n├── README.md\n└── README.pt-br.md\n```\n\n---\n\n## How to Run the Project\n\n1. Clone the repository: `git clone https://github.com/jovinull/bixim.git`\n2. Follow the **Development Environment Setup** section above.\n3. Build for PC: `pio run -e native -t exec`\n4. Build and flash for ESP32: `pio run -e esp32dev -t upload`\n5. Follow the electrical schematic in the `/hardware` directory for peripheral assembly.\n\n## License\n\nThis project is open source and licensed under the MIT License. Feel free to fork, study the architecture, and contribute improvements.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjovinull%2Fbixim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjovinull%2Fbixim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjovinull%2Fbixim/lists"}