# 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:

```sh
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/`:

| File | Board |
|---|---|
| `micropython-esp32-cydstudio.bin` | CYD, custom image (frozen core, fixed heap) |
| `micropython-esp8266-frozen.bin` | NodeMCU, custom image |
| `micropython-esp32.bin` · `micropython-esp8266.bin` | Stock backups |

**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).

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

> **Warning:** with `--baud 460800` esptool leaves its stub at that speed and the next command cannot connect at 115200. If the port drops mid-write the board stays in download mode; no need to hold the button again, just rerun the command.

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

```sh
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.

```sh
# 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

```sh
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 **▶**:

```python
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](/en/docs/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')`.