CYD Studio › Docs › Getting started

Getting started

You prepare the board once: write the image, deploy the core. Everything after that happens in the browser. This page covers the PC-side steps for all three boards.

Requirements#

• Python 3.12 and the tools: pip install mpremote esptool mpy-cross pyserial
• The repository: git clone https://github.com/tarikgkhsn/CYD-Studio
• A serial port: COM3-style on Windows, /dev/ttyUSB0-style on Linux. To list them: python -c "import serial.tools.list_ports as l; [print(p.device) for p in l.comports()]"

1. WiFi settings#

boards/*/config.json is not in the repository because it holds the password. Copy the example and fill it in:

cp boards/cyd/config.example.json boards/cyd/config.json

Fields: ssid, password, static IP (ip, netmask, gateway, dns), fallback access point (ap_ssid, ap_password), hostname, rotation, cpu_freq. If the board cannot join the network it opens its own access point named ap_ssid, reachable at 192.168.4.1.

2. Flash#

Ready-made images live in firmware/:

CYD: the board's auto-reset circuit cannot drive IO0. Hold BOOT, tap RESET, keep BOOT held until the write finishes. flash.py runs esptool with --before no-reset --after no-reset --baud 115200; --koru keeps the filesystem (projects, config, logs).

python tools/flash.py COM3 firmware/micropython-esp32-cydstudio.bin --koru

NodeMCU: auto reset, no button. Leave it alone for ~10 seconds after flashing; LittleFS is doing its first format.

python tools/flash_esp8266.py COM3 --koru

ESP32 OLED: the stock image (micropython-esp32.bin) and the same BOOT procedure.

3. Deploy#

On boards with a frozen core only filesystem files are sent (main.py, boot.py, index.html, docs, samples). --frozen removes filesystem copies of frozen modules; this is mandatory, because a same-named .py on the filesystem shadows the one in the firmware and eats RAM.

# CYD
python tools/deploy.py --board cyd --port COM3 --frozen --samples --reset
# NodeMCU
python tools/deploy_mpy.py --board nodemcu --port COM4 --frozen --samples --reset
# ESP32 OLED (stock firmware; the core goes to the filesystem)
python tools/deploy.py --board oled --port COM6 --samples

• --samples also uploads the sample projects.
• --config overwrites the board's config.json; use it on the first install, then leave it out.
• --reset restarts the board at the end. mpremote leaves the board at the REPL; without this the panel does not come up.
• deploy.py reads each file's hash on the board and skips unchanged ones.

4. Watch the boot#

python tools/bootlog.py COM3 25
curl http://192.168.0.217/api/status

If the panel does not answer the board is off, in solo mode, crashed at boot, or stuck at the REPL. bootlog.py always tells the truth.

5. First project#

Open the panel (http://<board-ip>/), create hello.py with + new, write, press ▶:

import cyd

n = 0
while not cyd.should_stop():
    n += 1
    print('hello', n)
    if not cyd.sleep(1): break

print() output streams to the console at the bottom, ■ stops it. The rules and the whole cyd module: Writing projects.

USB bridge: the panel without WiFi#

tools/usb_panel.py COM4 --board nodemcu serves the panel over the serial cable at http://127.0.0.1:8080/ (not localhost: Windows tries IPv6 first and every request lags 2 seconds). The panel HTML is loaded from the PC; only /api/... requests go over serial, and the board's console output streams into the same window tagged [kart]. The port is busy while the bridge runs; close it before deploying.

Writing files#

PowerShell's Set-Content -Encoding utf8 adds a BOM at the start of the file and MicroPython reads it as a variable name (NameError). Write Python files with an editor or with Python: open(p, 'w', encoding='utf-8', newline='\n').

Last updated 2026-10-17 · This page as Markdown