Cydintosh

A Macintosh Plus emulator port for Cheap-Yellow-Display board (ESP32), with some little 68k Mac applications.

• Macintosh Plus emulation using umac and Musashi 68k emulator
• 240x320 LCD with touchpad emulation for mouse control
• Homebrew Mac applications built with Retro68 (Weather, WiFi status, etc.)
• IPC between Mac and ESP32 (WiFi scan, MQTT weather data)

Hardware BOM

Component	Quantity	Notes
CYD2USB (ESP32-2432S028)	1	ESP32 with ILI9341 240x320 LCD, XPT2046 touch
M2x3 Self-Tapping screw	4	For enclosure assembly

Note: The enclosure is only compatible with the CYD2USB (Type-C + micro USB) variant.

Getting Started

1. Flash: See Building to build and flash the firmware/ROM/disk image
2. Print: 3D print the enclosure from ./enclosure
3. Assemble: Mount the CYD into the enclosure and secure with four M2x3 self-tapping screws

Prerequisites for Emulator

• Mac Plus ROM v3 (4D1F8172, 128KB) rom.bin
• System 3.2 bootable disk image (400KB)
• HFS disk image (800KB cyd_800k.dsk provided, includes pre-built Mac apps for Cydintosh)

See also the pico-mac repo for ROM and disk image requirements.

Building

# Clone and initialize submodules
git clone --recursive https://github.com/likeablob/cydintosh
cd cydintosh

# If you cloned without --recursive, initialize submodules:
git submodule update --init --recursive

# Setup m68k configuration
(cd external/umac/external/Musashi && ln -sf ../../../../include/m68kconf.h m68kconf.h)

# Generate m68kops.c
(cd external/umac && make prepare)

# Create user configuration
cp include/user_config.h.tmpl include/user_config.h
# Edit include/user_config.h with your WiFi/MQTT settings

# Generate and flash patched ROM
python3 tools/generate_patched_rom.py path/to/rom.bin -o rom_patched.bin
esptool --port /dev/ttyUSB0 --baud 921600 write_flash 0x210000 rom_patched.bin

# Prepare disk image
# The cyd_800k.dsk includes pre-built Mac applications (CydCtl, Weather, WiFi).
# To create a fresh disk with System 3.2 using Mini vMac emulator:
#   ./Mini\ vMac system3.dsk cyd_800k.dsk
#   Then copy System folder from system3.dsk to cyd_800k.dsk in the emulator

# Finally, copy the prepared disk to data/disk.img
cp cyd_800k.dsk data/disk.img

# Build and upload firmware
# For the CYD (micro USB) variant, use `-e cyd`
# Add a new [env:xxx] section to platformio.ini for other minor variants.
pio run -e cyd2usb -t upload


# Upload disk image
pio run -e cyd2usb -t uploadfs

To use the Weather app, continue with Home Assistant Setup.

Development

# Format tracked C/C++ files
mise run format

# Check formatting without changes
mise run format:check

Mac Applications

Homebrew Mac applications for Cydintosh.

App	Description
Weather	Weather display via MQTT
CydCtl	Hardware control (backlight, RGB LED)
WiFi	WiFi status and scan

ESP32-Mac IPC Interface

The ESP32 exposes a command interface via memory-mapped region at 0xF00000. Mac applications read/write this shared memory to communicate with ESP32:

App	Commands
Weather	GET_WEATHER_DATA ...
CydCtl	GET_HW_STATE, SET_BACKLIGHT, SET_LED_RGB ...
WiFi	GET_WIFI_LIST, GET_WIFI_STATUS ...

See include/umac_ipc.h and mac-app/common/esp_ipc.h for full command definitions.

Weather App

flowchart LR
    HA["Home Assistant<br/>(Automation)"] -->|"Publish<br>(1h)"| MB[("MQTT Broker")]
    MB -->|"Data"| ESP["ESP32"]
    ESP -->|"Data"| MAC["Weather App"]
    ESP -.->|"Subscribe"| MB
    MAC -.->|"Polling<br>(30s)"| ESP
    
    linkStyle 0,1,2 stroke:#4CAF50,color:#4CAF50
    linkStyle 3,4 stroke:#999

Loading

1. Home Assistant automation publishes weather data to MQTT every hour
2. ESP32 subscribes to MQTT topics and stores received data
3. Weather App polls ESP32 via IPC every 30s and renders the data

Home Assistant Setup

You need to set up MQTT and a weather integration in Home Assistant to use the Weather app.

• MQTT Integration
• Weather Integrations
• Definitive guide to Weather integrations (Community)

1. In Home Assistant, go to Settings > Automations > Create Automation > Edit YAML
2. Paste the content of homeassistant/weather_to_mqtt.yaml
3. Edit the variables:

   variables:
     weather_entity: "weather.home"
     topic_prefix: "home/weather"
     location: "Chicago"

ESP32 Configuration

WiFi and MQTT broker credentials are configured in include/user_config.h:

...
#define WIFI_SSID       "YOUR_WIFI_SSID"
#define WIFI_PASSWORD   "YOUR_WIFI_PASSWORD"

#define MQTT_BROKER_URL "mqtt://192.168.1.100:1883"
#define MQTT_USERNAME   "YOUR_MQTT_USERNAME"
#define MQTT_PASSWORD   "YOUR_MQTT_PASSWORD"

Updating the Disk Image Manually

# Rebuild applications and update disk image
./tools/update-disk.sh data/disk.img

# Re-upload disk image
pio run -e cyd2usb -t uploadfs

Gallery

Acknowledgements

• Musashi - m68k emulator
• umac - Mac Plus emulator core
• pico-mac - Reference implementation for RP2040
• ESP32-Cheap-Yellow-Display - CYD community
• For dependencies, see also src/idf_component.yml

License

• Software: MIT
• External libraries: See respective licenses in external/

TODO

• Better icons for mac-apps

Related Projects

• likeablob/denki-kurage: Another CYD-based gadget
• Macbar (WIP): ESP32-S3 port utilizing PSRAM
• Macbento (WIP)