Web FastLED

Keys

Project

Get W×H (toolbar, after Save) — takes WIDTH and HEIGHT from sketch into LED window (also MATRIX_WIDTH, kMatrixWidth…); if build runs with other size from size box, it is rebuilt with sketch's size. On project load LED window keeps its size and build gets it instead of sketch's WIDTH / HEIGHT (Options → LED → W×H from sketch on load on: window takes sketch's size); wiring (MATRIX_TYPE, CONNECTION_ANGLE, STRIP_DIRECTION) are taken once; sketch without them gets wiring from its XY(): zigzag if odd rows are reversed there (y & 1, y % 2), else parallel, from bottom left to right; later wiring is set in Options → LED.

Project is .zip with sketch: main .ino plus other .ino, .h, .c, .cpp files (Arduino IDE sketch folder packed into zip). Each file opens in its own tab, main sketch first; tabs can be dragged; × on tab removes file from project (asks first; last file closes project); + after tabs adds new file (.ino, .h, .c, .cpp, .txt); double click on tab or F2 renames file (Enter takes name, Esc cancels). Changed file is marked with * until project is saved. Single .ino / .h files are added to open project.

Load ▾ opens menu: Local file… (Ctrl+O, or drop file on page) and Library (list opens by ›) — projects of server folder repo/ (next to index.html), listed in repo/index.json:

{ "items": [
  { "file": "GyverMatrix.zip", "name": "GyverMatrix 24×12", "board": "mega" },
  { "file": "soulmate/fire.c", "name": "Fire (Soulmate)" }
] }

file — path inside repo/: .zip project, .c sketch or .ino; name — text of menu (file name if omitted); board (nano / mega) is optional and is selected on load. Plain list ["a.zip", "b.c"] works too. Library item always opens as new project. With 10 and more items menu gets filter box.

Browser storage (last part of Load menu, list opens by ›): projects kept in this browser, newest first; Manage… opens window — drop .zip / .ino / .c there (or click to choose) to add, Open, ⤓ download, ✕ delete, Clear all. Storage belongs to this browser on this computer: clearing site data of browser removes it.

Save (Ctrl+S) opens window: name, Download as .zip or to Browser Storage (stored project of same name is replaced); last choice is default for Enter. Project goes as .zip with same file names, encodings and line endings; files that are not sketch sources stay in archive untouched.

Compile and run

✓ (F7) only compiles; Start (F5) compiles sketch and runs it; Pause (Space) stops sketch clock; Reset starts same build again from setup(); Catch-up (⏭, also in Options → Build, off by default) — after rebuild of running sketch (new size, profile) it continues from same moment, see “LED window”; off — it starts from beginning. Compiler is clang (LLVM) in browser: first time it is downloaded (about 26 MB), then comes from browser cache. Sketch, FastLED 3.7.8 and Arduino core run as WebAssembly in real time: millis() and delay() are real (or scaled by speed).

Conversions that g++ allows with -fpermissive get cast and warning in Problems. Unlike AVR: int is 32 bit, double is 64 bit, RAM / flash limits are not checked (Real CPU timing has exact AVR, see below).

Power limit: sketch that calls FastLED.setMaxPowerInVoltsAndMilliamps() is dimmed by FastLED as a whole when estimated current is over limit, as on real strip (e.g. 5 V, 1000 mA: white lines on many LEDs come out grey); Output says so after build. Options → Build → Power limit of sketch is off by default: these calls are dropped for build; turn it on to see what real strip does.

Speed and Real CPU timing

Sketch runs in one of two modes, switched by Real CPU timing button (chip with clock, next to LED window button; yellow when on, off by default).

Off: sketch is compiled by clang into WebAssembly and runs as fast as page can; FastLED.show() waits so that frames come every 20 ms of sketch time — 50 fps at 1×. Speed (dial icon in LED window): 0.1×…10× = 5…500 fps (double click — 1×). Sketch clock (millis(), micros(), delay()) runs at same speed, so effects that count frames and effects that count time keep their proportions. 3D view, size rebuild, profile build and catch-up work in this mode.

On: sketch is built with avr-gcc as for real board (see “Board binary”) and its .hex runs on emulated ATmega328P (Nano) or ATmega2560 (Mega) at 16 MHz, instruction by instruction: every delay, interrupt and FastLED.show() takes exactly as long as on board; int is 16 bit, RAM is 2 KB (Nano) or 8 KB (Mega), as on board. LED colors are read from data pin by pulse widths, as strip reads them (color order of strip: Options → LED → Display, GRB for WS2812B); Serial monitor talks to USART0 (Serial; Mega Serial1…3 run too, their output is not shown), Inputs drive pins and ADC (Mega: A0…A15); Memory and Profile tabs of panel show RAM and CPU time of board. Speed is 1×, 3D view, size rebuild, profile build and catch-up are off; size box only lays out LEDs read from pin. If computer cannot keep up with 16 MHz, board clock runs slower than real time; status bar then shows % of real speed.

Turning it on or off while sketch runs starts it again in new mode. fps in corner of LED window is frames per second (FastLED.show() calls; in Real CPU timing — frames read from pin).

Debugger (Real CPU timing)

Breakpoint: click line number (or just left of it): red dot appears left of number; click again removes it. With Real CPU timing on, board stops before that line runs: arrow and highlight show line, status bar says where, panel opens Debug tab — call stack (click goes to place), registers r0…r31, X / Y / Z, SP, PC, SREG (capital letter = flag set), cycles, RAM as hex (address box, links to variables and stack; changed since previous stop in yellow), list of breakpoints (× removes; line without code of its own moves to next one, “no code” — it never stops there).

Then: Step over (F10) — next line, calls are run through; Step into (F11) — into called function of sketch (library code is run through); Step out (Shift+F11) — until function returns; Continue (F5, Space or Pause button) — runs to next breakpoint. Pause while running stops board at once, as breakpoint does. Interrupts (millis timer, Serial) keep running inside steps; their code is passed over. Board time stands while stopped.

Build is optimized as in IDE (-Os, LTO): small functions are put into callers, lines are reordered, some lines have no code — steps can jump a little, as in any debugger of optimized code. Line that only calls function which optimizer put into caller (case 1: VUSpectrum();) stops at start of that copy; mark stays on breakpoint line. Breakpoint stops only when line really runs: in mode switch, when that mode comes. Variables by name come later; for now RAM view shows them (globals from address 0x100).

Board binary (real build)

Button with chip and arrow (next to Save) builds sketch for real board with avr-gcc 7.3.0, same compiler, flags and steps as Arduino IDE 2 (Arduino AVR core 1.8.6, FastLED 3.7.8 or version chosen in Options → FastLED, link-time optimization). Result is byte for byte what IDE gives: .hex, .hex with bootloader, .elf (with debug info), .eep, or all of them in .zip; Build only shows size report as IDE does. Compiler runs in browser: first time it is downloaded (about 16 MB), then comes from browser cache; first build of session takes some seconds more. FastLED 3.10.9 comes as source (rt/avr/fastled-3.10.9.tar.gz, 2.7 MB): first real build with it compiles library for board (about a minute), browser keeps it.

Whole project is built as saved (its encoding and line ends), with sizes from sketch itself: LED window size box does not apply. Libraries are found by #include, as in IDE: FastLED, SPI, Wire, SoftwareSerial, EEPROM. Errors are in Problems, log in Output. .c sketch (no .ino) is built as in emulator: its .c files are sketch, COLS / ROWS become WIDTH / HEIGHT, pattern.c gives setup() / loop() (Options → Build). “With bootloader” file uses bootloader chosen in Upload menu.

Upload to board (USB)

Upload (arrow into board, next to board binary button; Ctrl+U) makes real build and writes it to board over USB, as Arduino IDE does (avrdude): through bootloader, STK500v1 for Nano, STK500v2 for Mega 2560; device signature is checked, every page is read back and compared. Needs Web Serial: Chrome, Edge, Opera or new Firefox on computer.

▾ next to it opens menu: Upload to board; Port — Choose port… when none is chosen yet, else its name and Change (browser asks which port; choice is remembered); Release port — closes what page holds on port (Serial monitor) and forgets it, so other programs (Arduino IDE) can take it; Bootloader of Nano (as Processor menu of IDE): ATmega328P — Optiboot, 115200 baud, Nano since 2018 and most new ones; Old Bootloader — 57600 baud, older ones and many clones. Upload tries chosen one first, then other; when other one answers, it becomes chosen.

Serial monitor of board: in Serial Monitor panel choose speed (as in sketch's Serial.begin()) and Connect board; opening port resets board, as in IDE. While connected, input line sends to board. Upload closes monitor and opens it again after.

Port can be held by one program only: close serial monitor of Arduino IDE (or other terminal) first, or Release port here before using IDE.

USB drivers

Browser talks to board through serial port of operating system, so USB-serial chip of board needs its driver, same as for Arduino IDE (Web Serial does not replace it). Chip is written on board near USB socket; after choosing port, its name is shown in Upload menu (CH340, CH9102, FT232R…).

Linux: user must be in dialout group (sudo usermod -aG dialout $USER, then log in again); on Ubuntu package brltty grabs CH340 ports — remove it (sudo apt remove brltty). If port is missing in browser's list: other cable (many are charge-only), other USB socket, check Device Manager (Windows) for unknown device. Upload with no answer: right board (Nano / Mega) and bootloader, nothing else holds port, try Old Bootloader / ATmega328P.

File order on compile

As in Arduino IDE, all .ino files of sketch folder become one C++ file:

1. #include <Arduino.h> is put first.
2. Main .ino (named as project, or one with setup() and loop()) goes first, then other .ino files in alphabetical order, case ignored (real build: as IDE, upper case first). Tab order does not matter.
3. Prototypes of all functions are inserted before first function definition, so function may be called before it is defined, from any .ino.
4. #line marks keep file names and line numbers in errors.

So global variables and types of one .ino are visible in .ino files that come after it, not before. .h files are not compiled by themselves: they are included where #include says. .c / .cpp files of sketch folder (and src/) are compiled separately, each must include what it needs (Arduino.h, FastLED.h). Prototypes are not made for functions with default arguments and for templates — declare them yourself.

Devices

What is connected to board: LED Matrix (FastLED strip / matrix), Inputs (buttons, pots), OLED display (SSD1306 128×64 / 128×32 over I²C or SPI: libraries GyverOLED and SSD1306Wire of ThingPulse — controller is emulated as display sees it: commands, RAM, flip, invert, contrast; I²C scanner finds it at its address; closing its window stops sketch; emulator only for now). Devices group of toolbar: + adds device (or Detect from sketch: LED matrix when sketch uses FastLED, inputs always), device button shows / hides its window, right click on it — Show / hide window, Settings…, Remove. Settings: Options → Devices (list of devices, settings of picked one). Project keeps its devices in webfastled.json (no tab; Arduino IDE ignores it): it appears when devices differ from what sketch gives by itself (then LED wiring, rotation, mirror and 3D view go there too) and is saved with project. Without it devices come from sketch.

LED window

Controls are in title bar: size (24x12, 24-12, 2412) — Enter or leaving box rebuilds sketch with these WIDTH and HEIGHT (only for this build, code is not changed; with catch-up on running sketch continues from same moment, new size is shown once new build has caught up; #define NUM_LEDS 256 given as number equal to old WIDTH × HEIGHT follows new size), speed (see “Speed and Real CPU timing”), fit window to matrix, effects ▾ menu (grid, coordinates under cursor, strip route — line from leds[0] along indexes, green dot at start). Also there: Get W×H (size and wiring from sketch), rebuild with size of box, rotate view 90°, mirror. Closing window stops sketch.

3D wraps matrix (as window shows it, after rotate / mirror) on figure; ▾ next to it: figure, mode, rotation. Cylinder — matrix is its side: columns go round, rows go down, so running text runs round cylinder. Sphere — as many points as LEDs, spread by golden angle; each point shows LED under its longitude (x) and latitude (y, top row at north pole). Globe — latitude / longitude grid: rows are parallels, columns meridians, LEDs crowd to poles (as on real LED spheres, maps like Earth fit it best). Torus — columns go round ring, rows round tube (middle row on outer side); text runs round it. Disc (polar) — rows are rings from centre outwards, columns are angle clockwise from top: round panels, fire, tunnels, Lotus. Dome (polar) — same on hemisphere facing you, row 0 at pole. Dots — one dot per LED, back side dimmer (dot size and cylinder height: Options → LED → 3D); Solid (WebGL) — lit figure with LEDs as round dots on dark surface. Drag rotates (fling keeps it spinning), wheel / pinch / right+left drag zooms, double click — normal size and front view; fit makes window square around figure at its present size. Rotate on — figure turns by itself when left alone; off — it stays as left.

In toolbar, next to LED window button, in its own group: rebuild with size of size box (same as Enter in it), Real CPU timing (chip with clock: switch, yellow when on), rotate view by 90° clockwise (action: each click adds 90°, angle other than 0° is shown by small number on button), mirror horizontally (switch, highlighted when on), inputs window (blue while open; green dot — sketch reads pins: buttons, pots).

Catch-up (continue from same moment): new build runs fast (no waiting, no frames) from start up to time of old one, replaying inputs (buttons, sliders, Serial input) and same noise of floating pins, so time-driven things (mode switching by millis()) come to same place; arrays sized by WIDTH / HEIGHT are filled again.

LEDs grow and shrink with window, down to 1 screen pixel per LED; window is never narrower than its title bar. fps in corner — FastLED.show() calls per second. Wiring (zigzag / parallel, start corner, direction) and colors are in Options → LED.

.c sketches

Project (or single file) of .c files and without .ino is sketch too, in style of Soulmate / soulmatelights editor: often only draw() and globals, sizes as LED_COLS / LED_ROWS or COLS / ROWS. .c files are compiled as C++, like .ino (joined alphabetically, prototypes added).

On loading, sketch text itself is changed, so editor shows what is compiled (changed files get * mark, Save keeps changes):
1. LED_COLS, COLS → WIDTH; LED_ROWS, ROWS → HEIGHT (Options → Build, on by default). Defines that become #define WIDTH (WIDTH) are commented.
2. If sketch has no setup(), pattern.c from server root is inserted (Options → Build, on by default): its includes, defines and globals go to top of file (between // ===== pattern.c marks), its functions (XY(), setup(), loop() calling draw() and FastLED.show()) to end. What sketch has itself is commented in pattern (#define NUM_LEDS (N_LEDS) of sketch takes place of pattern's one, sketch's line is commented).

If sketch still has no setup() at build (option was off on loading), pattern.c is added for build only, errors in it are shown as pattern.c:line; it is read from server again on each build. Its size (16×16) is what Get W×H finds when sketch has no sizes of its own; size box overrides it as usual.

Panel

Problems — errors and warnings, click opens the place; they are also underlined in editor. Output — compiler log. Search — results of search box in toolbar: all files of project, as you type (Aa — match case, ab — whole word, .* — regular expression); click selects match in its file. Serial Monitor — Serial.print of sketch; line below sends text to Serial.read(); speed and Connect board — monitor of real board (see “Upload to board”). Ctrl+J shows / hides panel.

Profile — Real CPU timing off: with profile build on, each function of .ino files gets timer: calls per second, Busy (time of function itself, with library calls), Waits (delay(), FastLED.show() pacing inside it), Total (with called sketch functions), function that calls FastLED.show() is marked ▶; turning it on while sketch runs rebuilds (with catch-up on, continues from same moment); sketch runs slower with it. Real CPU timing on: share of board CPU time per function (sketch, FastLED, core, interrupts by name), always on, does not slow sketch.

Memory (Real CPU timing) — RAM of board as bar and table: variables (.data, .bss), heap, stack, free RAM between heap and stack; Now and Max / min since start (free RAM is filled with pattern at reset, growing stack and heap overwrite it). Red dot on tab: little reserve left (under 100 B) or stack ran into variables. Flash use of build is shown too.

Inputs

Pins used by running sketch, as if wires were connected to board. Pin in INPUT_PULLUP mode is button to GND (press = LOW) — D3 of GyverMatrix is its mode button. INPUT is button to 5V (press = HIGH; released, pin floats). Pins read by analogRead() get slider (or noise, as unconnected). Outputs show level or PWM, FastLED pin — number of LEDs. Hold Press; Shift+click keeps it pressed.

Options: Board / CPU

Board sets pins (A0…, Serial1-3 on Mega), EEPROM size and defines (ARDUINO_AVR_NANO / ARDUINO_AVR_MEGA2560); same board is used for board binary and Real CPU timing.

Sketch is compiled by clang (LLVM) in browser and runs as WebAssembly in real time. As with avr-gcc, -fpermissive conversions get cast and warning. Unlike AVR: int is 32 bit, double is 64 bit, RAM / flash limits are not checked (board binary and Real CPU timing are real AVR build).

Options: Build

Optimization — level of compiler for emulator build. Catch-up after rebuild: after rebuild of running sketch (new size, profile on / off) new build runs fast up to moment of old one with same inputs, then goes on; off — it starts from beginning.

Power limit of sketch: FastLED.setMaxPowerInVoltsAndMilliamps of sketch dims whole frame when estimated current is over limit, as on real strip; off — these calls are dropped. C++ standard library gives headers of libc++ (<vector>, <algorithm>) that AVR has not; some sketch functions (float sqrt(float)) may clash with its overloads.

.c sketches: add pattern.c — sketch of .c files without setup() gets pattern.c of server root (includes, sizes, leds[], XY(), setup(), loop()); what sketch has itself is commented in pattern.

Options: Editing

Encoding (UTF-8 / Windows-1251) and line endings (CRLF / LF) of each file are kept on save. Tab size, line numbers, word wrap, current line, whitespace and auto-close brackets are editor settings only.

Keep session — open project is stored in browser and restored next time.

Options: Matrix wiring

How strip index maps to X / Y, as GyverMatrix MATRIX_TYPE (layout), CONNECTION_ANGLE (start corner), STRIP_DIRECTION (direction); taken from sketch on load.

W×H from sketch on load: on — loading project or file sets LED window to WIDTH × HEIGHT of sketch; off — window keeps its size and build gets it instead of sketch's. .c sketches: ROWS / COLS → WIDTH / HEIGHT renames them on load.

Options: 3D

3D view of LED matrix (cylinder or flat, button in LED window). Dot size — LEDs of 3D view, 100% is largest. Cylinder height — 100%: LED pitch is same round and along axis, less — lower and wider, more — taller. Double click on slider returns default.

Options: Display

Strip color order is used by Real CPU timing: colors are read from data pin as strip reads them. As sketch (default): order from addLeds<…, ORDER> (or #define COLOR_ORDER). Fixed order (GRB for WS2812, WS2812B, SK6812; RGB for many WS2811) shows what that strip would show: wrong order in sketch swaps colors, as on real strip.

Dim colors: LED gives light proportional to its value (PWM), monitor does not. LED-like converts, so dim colors look as on real LEDs; Raw (slider left) shows values as they are; further right dim colors get brighter, up to +200% (default +100%, double click returns it). Brightest channel sets lift, others keep proportion, so colors stay saturated. Contrast darkens dark and middle tones, full brightness stays (default 0%). Raw ignores both.

OLED display

Controller SSD1306 (128×64, 128×32) is emulated as display sees it: commands and RAM come over I²C (Nano: A4 SDA, A5 SCL; Mega: 20, 21) or SPI (DC, CS pins). Libraries built in: GyverOLED, SSD1306Wire (ThingPulse; ESP8266 sketches run in emulator as AVR ones). Size, address and SPI pins come from sketch (on every build while project has no webfastled.json); set in Options → Devices, they go into webfastled.json. Emulator only for now.

Bus takes time as on board: I²C is 100 kHz unless Wire.setClock(400000) (SSD1306Wire sets 700 kHz itself) — picture of 1 KB takes about 100 ms at 100 kHz. With buffer picture goes to display only by update() (GyverOLED) / display() (SSD1306Wire); display that stays dark is explained in Output. Window: color, pixel grid (Options), speed of sketch, frames per second. Closing window stops sketch.

FastLED

FastLED 3.7.8 (Daniel Garcia, Mark Kriegsman and contributors, MIT license) is built in — last version before big rework of library (3.9, 3.10); projects of library are made for it. 3.10.9 can be chosen in Options → FastLED: emulator and real build (first real build compiles library for board, about a minute, then browser keeps it); programs get about 2 KB bigger.

Project can fix its version: line // @fastled 3.7.8 (or last — newest on site, builtin) in any source of sketch. It wins over Options; link with fastled= wins over it. Other settings that touch FastLED: Options → Board → Power limit of sketch, Devices → LED Matrix → Strip color order.

REST API

Link to this page with parameters opens it as set: index.html?project=GyverMatrixOS_v1.12_24x12.zip&w=24&h=12&3d=1&shape=cylinder&run=1. Parameters may also follow # (open page takes them without reload). Keys are case-insensitive. Options → REST API builds such link: project from list (library, browser storage), values of what is open now are filled in when tab opens (Current fills them again). What link sets is for this visit only: visitor's own settings and session (open project) stay.

Error (no such project, file not found) is shown in Output; rest of link still applies.

Offline

Site opened once (over https) starts without internet: page and scripts are kept in browser, also on iPhone / iPad home screen. Compilers and library are kept once used; Options → Offline → Make offline downloads checked ones in advance (clang about 26 MB, avr-gcc about 16 MB), Clear files drops them. When site does not answer, red offline is shown in LED window, left of fps. New build on server: page reloads into it by itself.

Клавиши

Проект

Get W×H (панель инструментов, после Save) — берёт WIDTH и HEIGHT из скетча в окно LED (также MATRIX_WIDTH, kMatrixWidth…); если сборка работает с другим размером из поля размера, она пересобирается с размером скетча. При загрузке проекта окно LED сохраняет свой размер, и сборка получает его вместо WIDTH / HEIGHT скетча (Options → LED → W×H from sketch on load включено: окно берёт размер скетча); схема подключения (MATRIX_TYPE, CONNECTION_ANGLE, STRIP_DIRECTION) берётся один раз; скетч без них получает схему из своей XY(): зигзаг, если там нечётные строки перевёрнуты (y & 1, y % 2), иначе параллельная, от левого нижнего угла вправо; дальше схема задаётся в Options → LED.

Проект — .zip со скетчем: главный .ino и другие файлы .ino, .h, .c, .cpp (папка скетча Arduino IDE, упакованная в zip). Каждый файл открывается в своей вкладке, главный — первым; вкладки можно перетаскивать; × на вкладке удаляет файл из проекта (с подтверждением; последний файл закрывает проект); + после вкладок добавляет новый файл (.ino, .h, .c, .cpp, .txt); двойной щелчок по вкладке или F2 переименовывает файл (Enter — принять, Esc — отмена). Изменённый файл помечен *, пока проект не сохранён. Отдельные файлы .ino / .h добавляются в открытый проект.

Load ▾ открывает меню: Local file… (Ctrl+O или перетащить файл на страницу) и Library (список раскрывается по ›) — проекты папки repo/ на сервере (рядом с index.html), перечисленные в repo/index.json:

{ "items": [
  { "file": "GyverMatrix.zip", "name": "GyverMatrix 24×12", "board": "mega" },
  { "file": "soulmate/fire.c", "name": "Fire (Soulmate)" }
] }

file — путь внутри repo/: проект .zip, скетч .c или .ino; name — текст в меню (если нет — имя файла); board (nano / mega) необязателен и выбирается при загрузке. Простой список ["a.zip", "b.c"] тоже работает. Пункт библиотеки всегда открывается как новый проект. При 10 и более пунктах в меню появляется поле фильтра.

Browser storage (последний раздел меню Load, список раскрывается по ›): проекты, сохранённые в этом браузере, новые сверху; Manage… открывает окно — перетащите туда .zip / .ino / .c (или щёлкните, чтобы выбрать) для добавления; Open, ⤓ скачать, ✕ удалить, Clear all. Хранилище принадлежит этому браузеру на этом компьютере: очистка данных сайта в браузере удаляет его.

Save (Ctrl+S) открывает окно: имя, Download as .zip или to Browser Storage (проект с тем же именем в хранилище заменяется); последний выбор — по умолчанию для Enter. Проект сохраняется как .zip с теми же именами файлов, кодировками и концами строк; файлы, которые не являются исходниками скетча, остаются в архиве нетронутыми.

Компиляция и запуск

✓ (F7) только компилирует; Start (F5) компилирует и запускает скетч; Pause (Space) останавливает часы скетча; Reset запускает ту же сборку заново с setup(); Catch-up (⏭, также в Options → Build, по умолчанию выключен) — после пересборки работающего скетча (новый размер, профиль) он продолжает с того же момента, см. «Окно LED»; выключен — начинает сначала. Компилятор — clang (LLVM) в браузере: в первый раз он скачивается (около 26 МБ), потом берётся из кэша браузера. Скетч, FastLED 3.7.8 и ядро Arduino работают как WebAssembly в реальном времени: millis() и delay() настоящие (или масштабируются скоростью).

Преобразования, которые g++ разрешает с -fpermissive, получают приведение типа и предупреждение в Problems. В отличие от AVR: int 32 бита, double 64 бита, пределы RAM / флеша не проверяются (в Real CPU timing — точный AVR, см. ниже).

Ограничение мощности: скетч, который вызывает FastLED.setMaxPowerInVoltsAndMilliamps(), FastLED притемняет целиком, когда оценка тока выше предела, как на настоящей ленте (например, 5 В, 1000 мА: белые линии на многих светодиодах выходят серыми); Output сообщает об этом после сборки. Options → Build → Power limit of sketch по умолчанию выключено: эти вызовы убираются из сборки; включите, чтобы увидеть, что сделает настоящая лента.

Скорость и Real CPU timing

Скетч работает в одном из двух режимов, переключаемых кнопкой Real CPU timing (чип с часами рядом с кнопкой окна LED; жёлтая — включено, по умолчанию выключено).

Выключено: скетч компилируется clang в WebAssembly и работает так быстро, как может страница; FastLED.show() ждёт, чтобы кадры шли каждые 20 мс времени скетча — 50 fps при 1×. Скорость (значок спидометра в окне LED): 0.1×…10× = 5…500 fps (двойной клик — 1×). Часы скетча (millis(), micros(), delay()) идут с той же скоростью, поэтому эффекты, считающие кадры, и эффекты, считающие время, сохраняют пропорции. 3D, пересборка под размер, профиль-сборка и catch-up работают в этом режиме.

Включено: скетч собирается avr-gcc, как для настоящей платы (см. «Прошивка для платы»), и его .hex исполняется на эмулированном ATmega328P (Nano) или ATmega2560 (Mega) на 16 МГц, команда за командой: каждая задержка, прерывание и FastLED.show() длятся ровно столько, сколько на плате; int 16 бит, RAM 2 КБ (Nano) или 8 КБ (Mega), как на плате. Цвета светодиодов читаются с пина данных по длительности импульсов, как их читает лента (порядок цветов ленты: Options → LED → Display, GRB для WS2812B); Serial monitor работает с USART0 (Serial; Serial1…3 у Mega тоже работают, их вывод не показывается), Inputs управляют пинами и АЦП (Mega: A0…A15); вкладки Memory и Profile панели показывают RAM и время процессора платы. Скорость 1×, 3D, пересборка под размер, профиль-сборка и catch-up отключены; поле размера только раскладывает светодиоды, считанные с пина. Если компьютер не успевает за 16 МГц, часы платы идут медленнее реального времени; строка состояния тогда показывает % от реальной скорости.

Включение или выключение во время работы скетча перезапускает его в новом режиме. fps в углу окна LED — кадры в секунду (вызовы FastLED.show(); в Real CPU timing — кадры, считанные с пина).

Отладчик (Real CPU timing)

Точка останова: клик по номеру строки (или чуть левее): слева от номера появляется красная точка; повторный клик убирает. При включённом Real CPU timing плата останавливается перед выполнением этой строки: стрелка и подсветка показывают строку, строка состояния — где, в панели открывается вкладка Debug — стек вызовов (клик переходит к месту), регистры r0…r31, X / Y / Z, SP, PC, SREG (заглавная буква = флаг установлен), такты, RAM в hex (поле адреса, ссылки на переменные и стек; изменившееся с прошлой остановки — жёлтым), список точек останова (× убирает; строка без своего кода переносится на следующую, «no code» — там остановки не будет).

Дальше: Step over (F10) — следующая строка, вызовы выполняются целиком; Step into (F11) — внутрь вызываемой функции скетча (код библиотек выполняется целиком); Step out (Shift+F11) — до возврата из функции; Continue (F5, Space или кнопка паузы) — до следующей точки останова. Пауза во время работы сразу останавливает плату, как точка останова. Прерывания (таймер millis, Serial) внутри шагов продолжают работать, их код проходится без остановки. Пока плата стоит, её время не идёт.

Сборка оптимизирована, как в IDE (-Os, LTO): мелкие функции встраиваются в вызывающие, строки переставляются, у некоторых строк нет своего кода — шаги могут немного прыгать, как в любом отладчике оптимизированного кода. Строка, которая только вызывает функцию, встроенную оптимизатором в вызывающую (case 1: VUSpectrum();), останавливается на начале этой копии; отметка остаётся на строке точки. Точка срабатывает, только когда строка действительно выполняется: в переключателе режимов — когда дойдёт до этого режима. Переменные по именам будут позже; пока их видно в окне RAM (глобальные — с адреса 0x100).

Прошивка для платы (настоящая сборка)

Кнопка с чипом и стрелкой (рядом с Save) собирает скетч для настоящей платы avr-gcc 7.3.0 — тем же компилятором, с теми же флагами и шагами, что Arduino IDE 2 (Arduino AVR core 1.8.6, FastLED 3.7.8, оптимизация при компоновке). Результат байт в байт совпадает с IDE: .hex, .hex с загрузчиком, .elf (с отладочной информацией), .eep или все сразу в .zip; Build only показывает отчёт о размере, как IDE. Компилятор работает в браузере: в первый раз скачивается (около 16 МБ), потом берётся из кэша браузера; первая сборка за сеанс идёт на несколько секунд дольше.

Проект собирается в том виде, в каком сохраняется (его кодировка и концы строк), с размерами из самого скетча: поле размера окна LED не применяется. Библиотеки находятся по #include, как в IDE: FastLED, SPI, Wire, SoftwareSerial, EEPROM. Ошибки — в Problems, лог — в Output. Скетч .c (без .ino) собирается как в эмуляторе: его файлы .c и есть скетч, COLS / ROWS становятся WIDTH / HEIGHT, pattern.c даёт setup() / loop() (Options → Build). Файл «с загрузчиком» использует загрузчик, выбранный в меню Upload.

Заливка в плату (USB)

Upload (стрелка в плату, рядом с кнопкой прошивки; Ctrl+U) делает настоящую сборку и записывает её в плату по USB, как Arduino IDE (avrdude): через загрузчик, STK500v1 для Nano, STK500v2 для Mega 2560; проверяется сигнатура чипа, каждая страница читается обратно и сравнивается. Нужен Web Serial: Chrome, Edge, Opera или новый Firefox на компьютере.

▾ рядом открывает меню: Upload to board; Port — Choose port…, пока порт не выбран, иначе его имя и Change (браузер спрашивает порт; выбор запоминается); Release port — закрывает то, что страница держит на порту (Serial monitor), и забывает его, чтобы порт могли взять другие программы (Arduino IDE); Bootloader для Nano (как меню Processor в IDE): ATmega328P — Optiboot, 115200 бод, Nano с 2018 года и большинство новых; Old Bootloader — 57600 бод, старые и многие клоны. Заливка сначала пробует выбранный, потом другой; если ответил другой, он становится выбранным.

Монитор порта платы: в панели Serial Monitor выберите скорость (как в Serial.begin() скетча) и нажмите Connect board; открытие порта перезагружает плату, как в IDE. Пока плата подключена, строка ввода отправляет текст на неё. Заливка закрывает монитор и потом открывает снова.

Порт может держать только одна программа: сначала закройте монитор порта Arduino IDE (или другой терминал), или нажмите здесь Release port перед работой в IDE.

Драйверы USB

Браузер работает с платой через последовательный порт операционной системы, поэтому USB-UART чипу платы нужен его драйвер, как и для Arduino IDE (Web Serial его не заменяет). Чип подписан на плате рядом с USB-разъёмом; после выбора порта его имя видно в меню Upload (CH340, CH9102, FT232R…).

Linux: пользователь должен быть в группе dialout (sudo usermod -aG dialout $USER, потом войти заново); в Ubuntu пакет brltty захватывает порты CH340 — удалите его (sudo apt remove brltty). Если порта нет в списке браузера: другой кабель (многие только для зарядки), другой USB-разъём, проверьте Диспетчер устройств (Windows) на неизвестное устройство. Если загрузчик не отвечает: правильная плата (Nano / Mega) и загрузчик, порт не занят другой программой, попробуйте Old Bootloader / ATmega328P.

Порядок файлов при компиляции

Как в Arduino IDE, все файлы .ino папки скетча становятся одним файлом C++:

1. Первым ставится #include <Arduino.h>.
2. Главный .ino (названный как проект или тот, где setup() и loop()) идёт первым, затем остальные .ino по алфавиту без учёта регистра (в настоящей сборке — как в IDE, заглавные первыми). Порядок вкладок не важен.
3. Прототипы всех функций вставляются перед первым определением функции, поэтому функцию можно вызывать до её определения из любого .ino.
4. Метки #line сохраняют имена файлов и номера строк в ошибках.

Поэтому глобальные переменные и типы одного .ino видны в .ino, идущих после него, но не до. Файлы .h сами не компилируются: они включаются там, где стоит #include. Файлы .c / .cpp папки скетча (и src/) компилируются отдельно, каждый должен подключать то, что ему нужно (Arduino.h, FastLED.h). Прототипы не создаются для функций с аргументами по умолчанию и для шаблонов — объявите их сами.

Устройства

То, что подключено к плате: LED Matrix (лента / матрица FastLED), Inputs (кнопки, потенциометры), OLED display (SSD1306 128×64 / 128×32 по I²C или SPI: библиотеки GyverOLED и SSD1306Wire от ThingPulse — контроллер эмулируется так, как его видит дисплей: команды, RAM, переворот, инверсия, контраст; I²C-сканер находит его по адресу; закрытие окна останавливает скетч; пока только в эмуляторе). Группа Devices на панели: + добавляет устройство (или Detect from sketch: LED-матрица, если скетч использует FastLED, Inputs — всегда), кнопка устройства показывает / прячет его окно, правый клик по ней — Show / hide window, Settings…, Remove. Настройки: Options → Devices (список устройств, настройки выбранного). Проект хранит свои устройства в webfastled.json (без вкладки; Arduino IDE его не замечает): файл появляется, когда устройства отличаются от тех, что дает сам скетч (тогда туда же идут разводка, поворот, отражение и 3D-вид матрицы), и сохраняется с проектом. Без него устройства берутся из скетча.

Окно LED

Управление в заголовке окна: размер (24x12, 24-12, 2412) — Enter или выход из поля пересобирает скетч с этими WIDTH и HEIGHT (только для этой сборки, код не меняется; при включённом catch-up работающий скетч продолжает с того же момента, новый размер показывается, когда новая сборка догонит; #define NUM_LEDS 256, заданный числом, равным старому WIDTH × HEIGHT, следует за новым размером), скорость (см. «Скорость и Real CPU timing»), fit — окно по матрице, меню эффектов ▾ (сетка, координаты под курсором, маршрут ленты — линия от leds[0] по индексам, зелёная точка в начале). Там же: Get W×H (размер и разводка из скетча), пересборка с размером из поля, поворот вида на 90°, отражение. Закрытие окна останавливает скетч.

3D натягивает матрицу (как её показывает окно, после поворота / зеркала) на фигуру; ▾ рядом: фигура, режим, вращение. Cylinder — матрица — его бок: столбцы идут по кругу, строки вниз, поэтому бегущая строка бежит вокруг цилиндра. Sphere — столько точек, сколько светодиодов, разложенных по золотому углу; каждая точка показывает светодиод под своей долготой (x) и широтой (y, верхняя строка на северном полюсе). Globe — сетка широт / долгот: строки — параллели, столбцы — меридианы, светодиоды сгущаются к полюсам (как на настоящих LED-сферах, карты вроде Земли ложатся лучше всего). Torus — столбцы идут вокруг кольца, строки вокруг трубки (средняя строка снаружи); текст бежит вокруг. Disc (полярный) — строки — кольца от центра наружу, столбцы — угол по часовой стрелке от верха: круглые панели, огонь, туннели, Lotus. Dome (полярный) — то же на полусфере, обращённой к вам, строка 0 на полюсе. Dots — точка на светодиод, задняя сторона тусклее (размер точки и высота цилиндра: Options → LED → 3D); Solid (WebGL) — освещённая фигура со светодиодами-кружками на тёмной поверхности. Перетаскивание вращает (бросок продолжает вращение), колесо / щипок / правая+левая кнопки — масштаб, двойной клик — обычный размер и вид спереди; fit делает окно квадратным вокруг фигуры текущего размера. Rotate включено — фигура сама вращается, когда её не трогают; выключено — остаётся как оставили.

В панели инструментов рядом с кнопкой окна LED, в своей группе: пересборка с размером из поля (то же, что Enter в нём), Real CPU timing (чип с часами: переключатель, жёлтый, когда включён), поворот вида на 90° по часовой (действие: каждый клик добавляет 90°, угол кроме 0° показан маленьким числом на кнопке), зеркало по горизонтали (переключатель, подсвечен, когда включён), окно inputs (синее, пока открыто; зелёная точка — скетч читает пины: кнопки, потенциометры).

Catch-up (продолжить с того же момента): новая сборка быстро идёт (без ожиданий и кадров) от начала до времени старой, повторяя входы (кнопки, ползунки, ввод Serial) и тот же шум висящих пинов, поэтому то, что идёт по времени (смена режимов по millis()), приходит в то же место; массивы по WIDTH / HEIGHT заполняются заново.

Светодиоды растут и уменьшаются вместе с окном, до 1 пикселя экрана на светодиод; окно не бывает уже своего заголовка. fps в углу — вызовы FastLED.show() в секунду. Схема подключения (зигзаг / параллельная, начальный угол, направление) и цвета — в Options → LED.

Скетчи .c

Проект (или один файл) из файлов .c без .ino — тоже скетч, в стиле Soulmate / редактора soulmatelights: часто только draw() и глобальные переменные, размеры как LED_COLS / LED_ROWS или COLS / ROWS. Файлы .c компилируются как C++, как .ino (склеиваются по алфавиту, добавляются прототипы).

При загрузке сам текст скетча меняется, чтобы редактор показывал то, что компилируется (изменённые файлы получают *, Save сохраняет изменения):
1. LED_COLS, COLS → WIDTH; LED_ROWS, ROWS → HEIGHT (Options → Build, включено по умолчанию). Define, ставшие #define WIDTH (WIDTH), комментируются.
2. Если в скетче нет setup(), вставляется pattern.c из корня сервера (Options → Build, включено по умолчанию): его include, define и глобальные переменные идут в начало файла (между метками // ===== pattern.c), его функции (XY(), setup(), loop(), вызывающая draw() и FastLED.show()) — в конец. То, что есть в самом скетче, комментируется в pattern (#define NUM_LEDS (N_LEDS) скетча встаёт на место такого же в pattern, строка скетча комментируется).

Если при сборке в скетче всё ещё нет setup() (опция была выключена при загрузке), pattern.c добавляется только в сборку, ошибки в нём показываются как pattern.c:строка; он читается с сервера заново при каждой сборке. Его размер (16×16) находит Get W×H, когда у скетча нет своих размеров; поле размера, как обычно, его переопределяет.

Панель

Problems — ошибки и предупреждения, клик открывает место; они также подчёркнуты в редакторе. Output — лог компилятора. Search — результаты поля поиска в панели инструментов: все файлы проекта, по мере ввода (Aa — учитывать регистр, ab — слово целиком, .* — регулярное выражение); клик выделяет совпадение в его файле. Serial Monitor — Serial.print скетча; строка внизу отправляет текст в Serial.read(); скорость и Connect board — монитор настоящей платы (см. «Заливка в плату»). Ctrl+J показывает / скрывает панель.

Profile — при выключенном Real CPU timing: с профиль-сборкой каждая функция файлов .ino получает таймер: вызовы в секунду, Busy (время самой функции с вызовами библиотек), Waits (delay(), ожидание кадра в FastLED.show() внутри неё), Total (с вызванными функциями скетча), функция, вызывающая FastLED.show(), отмечена ▶; включение во время работы скетча пересобирает его (при включённом catch-up — с того же момента); скетч с ней работает медленнее. При включённом Real CPU timing: доля процессорного времени платы по функциям (скетч, FastLED, ядро, прерывания по именам), всегда включено, скетч не замедляет.

Memory (Real CPU timing) — RAM платы полосой и таблицей: переменные (.data, .bss), куча, стек, свободная RAM между кучей и стеком; «сейчас» и максимум / минимум с начала (свободная RAM при сбросе заполняется узором, растущие стек и куча его затирают). Красная точка на вкладке: мало запаса (меньше 100 Б) или стек наехал на переменные. Показан и расход флеша сборки.

Inputs

Пины, которые использует работающий скетч, как если бы к плате были подключены провода. Пин в режиме INPUT_PULLUP — кнопка на GND (нажата = LOW) — D3 в GyverMatrix — кнопка режимов. INPUT — кнопка на 5V (нажата = HIGH; отпущена — пин висит). Пины, читаемые analogRead(), получают ползунок (или шум, как неподключённые). Выходы показывают уровень или ШИМ, пин FastLED — число светодиодов. Удерживайте Press; Shift+клик оставляет её нажатой.

Options: Board / CPU

Плата задает пины (A0…, Serial1-3 у Mega), размер EEPROM и определения (ARDUINO_AVR_NANO / ARDUINO_AVR_MEGA2560); та же плата используется для прошивки и Real CPU timing.

Скетч компилируется clang (LLVM) в браузере и выполняется как WebAssembly в реальном времени. Как и в avr-gcc, преобразования -fpermissive получают приведение типа и предупреждение. В отличие от AVR: int — 32 бита, double — 64 бита, пределы RAM / flash не проверяются (прошивка и Real CPU timing — настоящая сборка для AVR).

Options: Build

Optimization — уровень компилятора для сборки эмулятора. Catch-up after rebuild: после пересборки работающего скетча (новый размер, профиль вкл / выкл) новая сборка быстро доходит до момента старой с теми же вводами и идет дальше; выкл — начинает с нуля.

Power limit of sketch: FastLED.setMaxPowerInVoltsAndMilliamps скетча приглушает весь кадр, когда расчетный ток выше предела, как на настоящей ленте; выкл — эти вызовы отбрасываются. C++ standard library дает заголовки libc++ (<vector>, <algorithm>), которых нет в AVR; некоторые функции скетча (float sqrt(float)) могут конфликтовать с ее перегрузками.

.c sketches: add pattern.c — скетч из .c-файлов без setup() получает pattern.c из корня сервера (includes, размеры, leds[], XY(), setup(), loop()); то, что есть в скетче, в pattern закомментировано.

Options: Editing

Кодировка (UTF-8 / Windows-1251) и концы строк (CRLF / LF) каждого файла сохраняются. Размер табуляции, номера строк, перенос, текущая строка, пробелы и автозакрытие скобок — только настройки редактора.

Keep session — открытый проект хранится в браузере и восстанавливается при следующем запуске.

Options: Matrix wiring

Как номер светодиода ленты соответствует X / Y, как в GyverMatrix: MATRIX_TYPE (layout), CONNECTION_ANGLE (start corner), STRIP_DIRECTION (direction); берется из скетча при загрузке.

W×H from sketch on load: вкл — загрузка проекта или файла ставит окну LED размер WIDTH × HEIGHT скетча; выкл — окно сохраняет размер, а сборка получает его вместо размера скетча. .c sketches: ROWS / COLS → WIDTH / HEIGHT переименовывает их при загрузке.

Options: 3D

3D-вид LED-матрицы (цилиндр или плоскость, кнопка в окне LED). Dot size — размер светодиодов 3D-вида, 100% — наибольший. Cylinder height — 100%: шаг светодиодов одинаков по окружности и вдоль оси, меньше — ниже и шире, больше — выше. Двойной клик по ползунку возвращает значение по умолчанию.

Options: Display

Strip color order используется в Real CPU timing: цвета читаются с пина данных так, как их читает лента. As sketch (по умолчанию): порядок из addLeds<…, ORDER> (или #define COLOR_ORDER). Заданный порядок (GRB у WS2812, WS2812B, SK6812; RGB у многих WS2811) показывает то, что показала бы такая лента: неверный порядок в скетче меняет цвета местами, как на настоящей ленте.

Dim colors: светодиод светит пропорционально значению (ШИМ), монитор — нет. LED-like пересчитывает, и тусклые цвета выглядят как на настоящих светодиодах; Raw (ползунок слева) показывает значения как есть; правее тусклые цвета еще ярче, до +200% (по умолчанию +100%, двойной клик возвращает). Подъем задается самым ярким каналом, остальные сохраняют пропорцию — цвета остаются насыщенными. Contrast затемняет темные и средние тона, полная яркость остается (по умолчанию 0%). Raw игнорирует оба.

OLED-дисплей

Контроллер SSD1306 (128×64, 128×32) эмулируется так, как его видит дисплей: команды и RAM приходят по I²C (Nano: A4 SDA, A5 SCL; Mega: 20, 21) или SPI (пины DC, CS). Встроены библиотеки GyverOLED и SSD1306Wire (ThingPulse; скетчи для ESP8266 идут в эмуляторе как для AVR). Размер, адрес и пины SPI берутся из скетча (при каждой сборке, пока в проекте нет webfastled.json); заданные в Options → Devices попадают в webfastled.json. Пока только в эмуляторе.

Шина занимает время, как на плате: I²C — 100 кГц, если нет Wire.setClock(400000) (SSD1306Wire сам ставит 700 кГц) — кадр в 1 КБ идет около 100 мс на 100 кГц. С буфером картинка уходит на дисплей только по update() (GyverOLED) / display() (SSD1306Wire); почему дисплей темный — пишется в Output. Окно: цвет, сетка пикселей (Options), скорость скетча, кадры в секунду. Закрытие окна останавливает скетч.

FastLED

Встроена FastLED 3.7.8 (Daniel Garcia, Mark Kriegsman и другие, лицензия MIT) — последняя версия до большой переделки библиотеки (3.9, 3.10); проекты библиотеки сделаны под нее. В Options → FastLED можно выбрать 3.10.9: эмулятор и настоящая сборка (первая сборка для платы компилирует библиотеку, около минуты, дальше браузер ее хранит); программы примерно на 2 КБ больше.

Проект может задать версию сам: строка // @fastled 3.7.8 (или last — самая новая на сайте, builtin) в любом исходнике скетча. Она главнее Options; fastled= в ссылке главнее ее. Другие настройки, касающиеся FastLED: Options → Board → Power limit of sketch, Devices → LED Matrix → Strip color order.

REST API

Ссылка на страницу с параметрами открывает её в заданном виде: index.html?project=GyverMatrixOS_v1.12_24x12.zip&w=24&h=12&3d=1&shape=cylinder&run=1. Параметры можно писать и после # (открытая страница примет их без перезагрузки). Регистр ключей не важен. Ссылку собирает Options → REST API: проект из списка (библиотека, хранилище браузера), при открытии закладки сразу подставляются значения того, что открыто сейчас (Current — подставить заново). Заданное ссылкой действует только в этот визит: собственные настройки и сессия посетителя (открытый проект) остаются.

Ошибка (нет такого проекта, файл не найден) выводится в Output; остальная часть ссылки всё равно применяется.

Офлайн

Сайт, открытый хотя бы раз (по https), запускается без интернета: страница и скрипты хранятся в браузере, в том числе на экране «Домой» iPhone / iPad. Компиляторы и библиотека сохраняются, когда ими воспользовались; Options → Offline → Make offline заранее скачивает отмеченное (clang около 26 МБ, avr-gcc около 16 МБ), Clear files удаляет. Если сайт не отвечает, в окне LED слева от fps горит красное offline. Новая сборка на сервере: страница сама перезагружается в неё.