Flashiibo FEB SDK & Tooling

Warning

BETA & EXPERIMENTAL WARNING

This repository, the FEB SDK, container format, and build tooling are in BETA and EXPERIMENTAL status.
APIs, header definitions, and runtime contracts are under active development. Breaking changes might happen without warning.

The Flashiibo Executable Binary (.feb) ecosystem enables developers to write, compile, and distribute standalone games and mini-applications for the Flashiibo Gen3 platform.

Applications run inside a sandboxed virtual runtime with a 60 Hz frame cycle, monochrome OLED graphics, and deterministic 4-button hardware navigation—without modifying or reflashing the MCU firmware.

---

Hardware Specifications

Property	Value	Notes
Target Platform	Flashiibo Pro Gen3	Requires firmware >= 26.10.6 (Sandboxed VM)
Display	128×64 (default) or 64×32 (legacy) Monochrome OLED	1-bit per pixel (XOR sprite drawing)
Frame Rate	60 Hz	Hardware timer-driven execution tick
Address Space	4,096 Bytes	Deterministic memory layout
Input Controls	4 Physical Buttons	Fixed directional mapping
Container Format	.feb (Flashiibo Executable Binary)	100-byte packed header + bytecode
Distribution	/feb/*.feb on SPI Flash	Loaded using Flashiibo Pro Tools on Web or Mobile

---

Deterministic Hardware Controls

Flashiibo Gen3 features four physical buttons:

                  ┌──────────────┐
                  │    [ UP ]    │
                  │ (FEB_KEY_UP) │
                  │   Key: 0x2   │
  ┌───────────────┴──────────────┴───────────────┐
  │   [ BACK ]                         [ OK ]    │
  │ (FEB_KEY_LEFT)                (FEB_KEY_RIGHT)│
  │   Key: 0x4                       Key: 0x6    │
  └───────────────┬──────────────┬───────────────┘
                  │   [ DOWN ]   │
                  │(FEB_KEY_DOWN)│
                  │   Key: 0x8   │
                  └──────────────┘

Physical Button	C Constant	Hex Code	Primary Role
UP	FEB_KEY_UP	0x2	Directional UP / Jump / Rotate
DOWN	FEB_KEY_DOWN	0x8	Directional DOWN / Crouch
BACK	FEB_KEY_LEFT / FEB_KEY_BACK	0x4	Directional LEFT / Cancel
OK	FEB_KEY_RIGHT / FEB_KEY_OK	0x6	Directional RIGHT / Select

Important

Emergency Exit Chord: Pressing UP and DOWN simultaneously guarantees immediate return to the Flashiibo device menu. Long-press on BACK is NOT used as an exit trigger, making BACK completely safe for gameplay movement.

---

Quickstart

Pre-compiled Releases

Pre-compiled .feb binaries for all games (2048, Flappy Bird, Sokoban, Digital Pet, and the complete ZIP bundle) are automatically built and published on the GitHub Releases page on every update and version tag. Developer demos and starter templates remain available in examples/.

Prerequisites

• Python 3.8 or newer
• GNU Make

Build All Included Apps

# Clone the repository
git clone https://github.com/flashiibo/feb-sdk.git
cd feb-sdk

# Build all applications into build/
make all

# Package distribution files into dist/ (binaries, zip bundle, sha256sums)
make dist

# Test games in the desktop Pygame simulator
make sim                   # Runs default 2048.feb
make sim GAME=digital_pet  # Runs Digital Pet
make sim GAME=sokoban      # Runs Sokoban
make sim GAME=flappy_bird  # Runs Flappy Bird

# Run automated test suite
make test

Build a Single App

cd examples/2048
make
# Generates 2048.feb

See SIMULATOR.md for complete manual testing controls, palette themes, and automated headless CI testing guides.

---

Repository Layout

feb-sdk/
├── README.md               <-- This documentation
├── SIMULATOR.md            <-- Desktop simulator guide (manual & automated testing)
├── SPEC.md                 <-- 100-byte .feb binary container specification
├── LICENSE                 <-- MIT License
├── Makefile                <-- Root build, simulation, and test orchestrator
├── include/
│   └── feb.h              <-- Flashiibo C SDK definitions & prototypes
├── tools/
│   ├── feb_sim.py         <-- Pygame-based desktop FEB simulator
│   ├── feb_vm.py          <-- Virtual machine engine (CHIP-8 / SCHIP / Flashiibo)
│   ├── feb_fonts.py       <-- Embedded u8g2 bitmap fonts & glyph decoder
│   ├── feb_build.py       <-- C / Assembly compiler and packager
│   ├── make_feb.py        <-- .feb binary container generator
│   └── assemble_chip8.py  <-- Virtual machine bytecode assembler
├── examples/
│   ├── 2048/              <-- Full 2048 puzzle game implementation (128x64)
│   │   ├── main.c
│   │   └── Makefile
│   ├── button_demo/       <-- Hardware 4-button input demo & press counter (128x64)
│   │   ├── main.c
│   │   └── Makefile
│   ├── digital_pet/       <-- Advanced virtual pet simulation with 16-byte persistent saving (128x64)
│   │   ├── main.c
│   │   └── Makefile
│   ├── draw_demo/         <-- Vector geometry & shapes demo application (128x64)
│   │   ├── main.c
│   │   └── Makefile
│   ├── flappy_bird/       <-- Flappy Bird arcade game with physics & collision (128x64)
│   │   ├── main.c
│   │   └── Makefile
│   ├── sokoban/           <-- 10-level Sokoban puzzle game with immovable blocks & saving (128x64)
│   │   ├── main.c
│   │   └── Makefile
│   └── template/          <-- Starter template with 4-way movement (128x64)
│       ├── main.c
│       └── Makefile
├── test/                  <-- Automated test suite
│   ├── test_sim.py        <-- Simulator unit & integration tests
│   └── test_tooling.py    <-- Compiler and packaging verification suite
└── docs/
    └── c_development_guide.md <-- In-depth C programming guide

---

C SDK API Reference (feb.h)

Include the C SDK header in your application:

#include "feb.h"

Display & Drawing Modes (Default: 128×64 Super-CHIP Mode)

• void feb_set_high_res(bool enable);: Switches between 128×64 high-resolution mode (true, default) and legacy 64×32 mode (false).
• void feb_clear_screen(void);: Clears the display buffer.
• void feb_set_draw_mode(uint8_t mode);: Sets active draw mode (FEB_DRAW_MODE_XOR, SET, CLEAR, OPAQUE, or INVERTED_OPAQUE).
• bool feb_draw_sprite(uint8_t x, uint8_t y, const uint8_t *sprite, uint8_t height);: XOR draws an 8-pixel wide sprite of height 1..15. Calling it a second time at the same position erases the sprite. Returns true if a collision occurred.
• bool feb_draw_sprite16(uint8_t x, uint8_t y, const uint8_t *sprite);: XOR draws a 16×16 pixel sprite in 128×64 mode (32 bytes). Returns true if a collision occurred.
• void feb_draw_digit(uint8_t x, uint8_t y, uint8_t digit);: Renders built-in hex digit (0..15).

Fast Geometric Primitives & Collision

• void feb_draw_pixel(uint8_t x, uint8_t y);: Plots single pixel at (x, y) using active draw mode.
• void feb_draw_line(uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1);: Draws line via Bresenham's algorithm.
• void feb_draw_hline(uint8_t x, uint8_t y, uint8_t len);: Draws fast horizontal line.
• void feb_draw_vline(uint8_t x, uint8_t y, uint8_t len);: Draws fast vertical line.
• void feb_draw_rect(uint8_t x, uint8_t y, uint8_t w, uint8_t h);: Draws outline rectangle.
• void feb_fill_rect(uint8_t x, uint8_t y, uint8_t w, uint8_t h);: Draws filled solid rectangle.
• void feb_draw_rrect(uint8_t x, uint8_t y, uint8_t w, uint8_t h);: Draws outline rounded rectangle with 1px corner radius.
• void feb_fill_rrect(uint8_t x, uint8_t y, uint8_t w, uint8_t h);: Draws filled solid rounded rectangle with 1px corner radius.
• void feb_draw_triangle(uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2);: Draws outline triangle connecting 3 vertices.
• void feb_draw_circle(uint8_t x, uint8_t y, uint8_t r);: Draws outline circle.
• void feb_fill_circle(uint8_t x, uint8_t y, uint8_t r);: Draws filled solid circle.
• bool feb_test_pixel(uint8_t x, uint8_t y);: Non-destructive zero-RAM collision test against framebuffer pixels.

Typography & Number Formatting

• uint8_t feb_draw_string(uint8_t x, uint8_t y, const char *str, uint8_t font_id);: Renders ASCII string; advances X.
• uint8_t feb_draw_char(uint8_t x, uint8_t y, char ch, uint8_t font_id);: Renders single ASCII character; advances X.
• uint8_t feb_string_width(const char *str, uint8_t font_id);: Measures pixel width of string.
• uint8_t feb_draw_number(uint8_t x, uint8_t y, uint16_t num, uint8_t font_id);: Formats 16-bit integer (0..65535); advances X.
• Fonts: FEB_FONT_4X6 (0), FEB_FONT_6X10 (1, default UI), FEB_FONT_RETRO_8X8 (2).

Input & Button Polling

• uint8_t feb_get_keys(void);: Non-blocking instantaneous bitmask of 4 physical buttons (FEB_BTN_UP, FEB_BTN_DOWN, FEB_BTN_LEFT, FEB_BTN_RIGHT).
• uint8_t feb_wait_key(void);: Blocks until a button is pressed; returns key code (0x2, 0x8, 0x4, 0x6).
• bool feb_is_key_down(uint8_t key);: Checks if a specific key is held.

Timing & Randomness

• uint8_t feb_rand(uint8_t mask);: Returns pseudo-random 8-bit integer masked with mask.
• void feb_set_delay_timer(uint8_t val);: Sets the 60 Hz delay timer countdown.
• uint8_t feb_get_delay_timer(void);: Reads the current 60 Hz delay timer value.
• void feb_delay_frames(uint8_t frames);: Delays execution for N frames (~16.6 ms per frame).

Lifecycle & Persistence

• void feb_exit(void);: Immediately terminates the program and returns to the FEB Runner menu (alias: feb_quit()).
• void feb_save_flags(const uint8_t *data, uint8_t len);: Persists up to 16 bytes to /feb/saves/<app_name>.sav.
• void feb_load_flags(uint8_t *data, uint8_t len);: Loads persistent state from companion .sav.

---

Creating Your Own App

1. Copy the starter template:

   cp -r examples/template examples/my_app

2. Edit examples/my_app/main.c and customize your logic.
3. Update examples/my_app/Makefile with your app title and author.
4. Build your .feb file:

   cd examples/my_app
   make

5. See docs/c_development_guide.md for full architectural patterns and best practices.

---

Deploying to Hardware

Note

Running .feb applications requires Flashiibo Pro Gen3 firmware >= 26.10.6.

1. Connect your Flashiibo Pro Gen3 to your computer or smartphone (USB or Web Bluetooth).
2. Open the Flashiibo companion application or Web Tool.
3. Upload your .feb binary into the /feb/ folder on device storage.
4. On your Flashiibo, scroll to FEB Runner, select your app, and press OK!

---

License

This project is licensed under the MIT License - see the LICENSE file for details.