AREA512

Welcome to AREA512!

AREA512 is an OS built for the Cardputer ADV and Cardputer v1.1, a tiny device with just 512KB of RAM and 8MB of flash storage!

It is based on FemtoRuby and includes MicroPython, so you can write Ruby and Python right on the Cardputer, then compile and run them — all on the device!

Quick Install

All you need is esptool:

pip install esptool

# Cardputer ADV
esptool.py -c esp32s3 -b 460800 write_flash --flash_mode dio --flash_size 8MB --flash_freq 80m 0x0 firmware/Area512Adv.bin

# Cardputer v1.1
esptool.py -c esp32s3 -b 460800 write_flash --flash_mode dio --flash_size 8MB --flash_freq 80m 0x0 firmware/Area512V11.bin

• If the port is not auto-detected, add -p /dev/ttyACM0 to the esptool.py command.
• Insert a FAT32-formatted microSD card into the Cardputer (it is used to store app data).

Using AREA512

The screen shows a listing of the current directory: directories first, then files. Source files (.rb / .py) and compiled files (.mrb / .mpy) are shown as separate entries with their extensions.

The following keys are available.

Applications

The following come preinstalled under /home/tool and /home/game.

Each app's directory also contains a README explaining how to use it!

Writer — /home/tool/writer

A word processor. From business documents to poetry, write anything you like!

Scheduler — /home/tool/scheduler

The greatest schedule management software.

Calc — /home/tool/calc

A spreadsheet. Manage all of your money.

Paint — /home/tool/paint

Draw anything!

Solitair — /home/game/solitair

The world's finest card game. Compete for the high score!

Bomb — /home/game/bomb

Launch it and you'll get it! That nostalgic game!

Space Lander — /home/game/space_lander

A lunar landing game written in Python.

Slide — /home/tool/slide

Displays numbered Markdown files as slides. Add files such as 1.md, 2.md, and 3.md to /home/tool/slide; they are displayed in numeric order.

Supported Markdown syntax:

• #, ##, and ### headings
• Lists starting with -
• Inline code enclosed in backticks
• Ruby code blocks enclosed in ```ruby and ```

Gallery — /home/tool/gallery

A gallery of the built-in Widget components.

Editing Code

The editor opened with e is a tiny vim running on the device. It has normal, insert, visual, operator, and command modes, plus search. Ruby and Python files have syntax highlighting, automatic indentation, code completion, diagnostics, and hover information. The keys your fingers remember mostly just work!

In insert mode, press Ctrl-N to open completion; it also opens automatically after . and uppercase letters in .rb and .py files.

Compiling and Running

The device compiles .rb into .mrb and .py into .mpy (bytecode) on the spot (see c / a in the key list). Ruby bytecode runs inside a sandbox, and Python bytecode runs with MicroPython.

Application Development

New applications should follow this layout.

Available Features

AREA512 provides the following features as built-ins. PicoRuby does not require require, and MicroPython does not require import, to use them.

See PicoRuby features and MicroPython features for the available APIs.

Directory Layout

An application is a single directory. Press R in the file manager to run it.

myapp/
├── main.manifest   # optional: lists .mrb or .mpy files to load, one per line
├── main.mrb        # Ruby entry point when there is no main.manifest
├── main.mpy        # Python entry point when there is no main.manifest or main.mrb
├── *.rb / *.mrb    # Ruby modules
├── *.py / *.mpy    # Python modules
└── image.h         # optional: splash image shown at launch

• If main.manifest lists .mrb files, they are loaded into a single sandbox in order. Put dependencies first and main.mrb last.
• If main.manifest lists .mpy files, MicroPython runs them in order. Put dependencies first and main.mpy last.
• Without main.manifest, main.mrb is executed if it exists; otherwise, main.mpy is executed.
• If none exists, No main.manifest, main.mrb or main.mpy in <directory> is shown.

Applications can use the built-in Widget components directly. See the Widget component documentation and the preinstalled /home/tool/gallery app.

Theme

Colors are read from /sdcard/Area512_data/etc/theme at boot. Without that file the defaults below are used. Edit it and reboot to apply.

background=0x000000
text=0xCFA45F
emphasis=0xF5972D
border=0xF5972D
selected=0xFFD966
box=0x241604

One key=0xRRGGBB per line; six hex digits, 0x required. Lines without = and unknown keys are ignored.

Bitmaps (the boot logo and an application's image.h) are drawn with emphasis and background only, the brighter of the two used for the set bits.

Building

Requirements

• ESP-IDF v5.5+
• Ruby + Bundler
• M5 Cardputer ADV or Cardputer v1.1
• USB-C cable

Setup

git clone --recursive git@github.com:engneer-hamachan/area512-dev.git
cd area512-dev
. $YOUR_ESP_IDF_PATH/export.sh
rake setup

If you already cloned without --recursive:

git submodule update --init --recursive

Build and Flash

# Cardputer ADV build
rake build

# Cardputer v1.1 build
rake build:v1.1

rake flash

Files under storage/ are embedded in the firmware as seed content and restored to the SD card's Area512_data/ directory on first boot (each top-level directory is only written if it does not exist yet on the card).

Contributing

AREA512 welcomes contributions of new apps and AREA512 artwork (splash images and such)!

License

MIT License