Справочник Wokwi

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Всем

Справочник Wokwi

Платформа Wokwi представляет собой облачную систему эмуляции электронных схем, обеспечивающую визуальную сборку проектов на микроконтроллерах Arduino, ESP32 и Raspberry Pi Pico.

Среда обрабатывает графические макеты, транслирует их во внутренние математические модели компонентов и выполняет пошаговую эмуляцию работы прошивки непосредственно в браузере.

Конфигурационный файл diagram.json хранит полное описание проекта, определяет состав аппаратных модулей, задаёт топологию электрических соединений и перечисляет внешние программные зависимости.

Система последовательно интерпретирует структуру файла, загружает соответствующие драйверы симуляции и инициализирует виртуальные устройства согласно заданным параметрам.

Архитектура конфигурационного файла diagram.json

Файл конфигурации содержит структурированный объект в формате JSON, разделяющий описание проекта на логические сегменты.

JSON (JavaScript Object Notation) — это просто способ записывать данные в виде текста, понятном и компьютеру, и человеку. Выглядит это как паспорт:

{ "Имя": "Петя", "Возраст": 25 }

В Wokwi этот паспорт описывает всю вашу схему.

Среда исполнения последовательно парсит объект parts, обрабатывает массив connections и загружает внешние ресурсы через секцию dependencies.

Платформа применяет строгую валидацию полей, сопоставляет идентификаторы компонентов с внутренним реестром устройств и вычисляет электрические цепи на основе заданных связей.

Поле	Тип данных	Назначение
`version`	Целое число	Версия спецификации формата конфигурации
`parts`	Массив объектов	Перечень размещённых компонентов схемы
`connections`	Массив объектов	Описание электрических связей между выводами
`dependencies`	Массив строк	Перечень внешних библиотек и пакетов кода

Раздел "parts" (Детали) - здесь перечислены все компоненты на вашей виртуальной плате. Каждый компонент — это отдельный объект в квадратных скобках [ ]. Как выглядит одна деталь:

  "parts": [
    {
      "type": "wokwi-esp32-devkit-v1",
      "id": "esp",
      "top": 0,
      "left": 0,
      "attrs": { }
    },
    {
      "type": "wokwi-led",
      "id": "led1",
      "top": 50,
      "left": 100,
      "attrs": { "color": "red" }
    }
  ]

type - Модель детали. Что это за компонент.
id - Уникальное имя. Как вы будете обращаться к этой детали в коде (если нужно). Обычно это esp для платы, led1, led2 для светодиодов.
top / left - Координаты на экране. Где нарисована эта деталь (в пикселях).
attrs - Свойства. Цвет, сопротивление, яркость и т.д.

Раздел "connections" (Соединения) - самый важный раздел. Здесь записано, какие пины (ножки) соединены друг с другом проводами. Выглядит это как список пар:

  "connections": [
    ["esp:13", "led1:A", "green"],
    ["led1:C", "esp:GND.1", "black"],
    ["esp:5V", "resistor:1", "red"],
    ["resistor:2", "led1:A", "green"]
  ]

Каждая строка в списке — это один провод. Она состоит из трех частей:

"Откуда" (пин источника)
"Куда" (пин приемника)
"Цвет провода на схеме" (для наглядности)

Разберем конкретные примеры:

["esp:13", "led1:A", "green"]. Перевод: «Соедини вывод GPIO 13 на ESP32 с анодом (+) светодиода led1 зеленым проводом». Это значит: когда вы в коде подадите сигнал на Pin(13), светодиод загорится.
["led1:C", "esp:GND.1", "black"]. Перевод: «Соедини катод (-) светодиода led1 с первым пином заземления (GND) на ESP32 черным проводом». Это замыкает цепь.
["esp:5V", "resistor:1", "red"]. Перевод: «Подай питание 5 Вольт с ESP32 на первый вывод резистора красным проводом».

Раздел "serialMonitor" (Монитор порта) - раздел маленький, но полезный. Он настраивает консоль (терминал), через которую вы видите print() в MicroPython.

  "serialMonitor": {
    "display": "always",
    "newline": "lf"
  }

"display": "always" — означает, что консоль будет открыта всегда, когда вы запускаете симуляцию.
"newline": "lf" — это настройка переноса строки (для Linux/Mac). Обычно менять не нужно.

Представьте, что вы собрали схему: ESP32, светодиод и резистор.

diagram.json будет выглядеть так:

{
  "version": 1,
  "author": "Иван Иванов",
  "editor": "wokwi",
  "parts": [
    { "type": "wokwi-esp32-devkit-v1", "id": "esp", "top": 0, "left": 0, "attrs": {} },
    { "type": "wokwi-led", "id": "led1", "top": 50, "left": 100, "attrs": { "color": "red" } },
    { "type": "wokwi-resistor", "id": "r1", "top": 80, "left": 150, "attrs": { "resistance": "220" } }
  ],
  "connections": [
    ["esp:13", "r1:1", "red"],
    ["r1:2", "led1:A", "green"],
    ["led1:C", "esp:GND.1", "black"]
  ],
  "serialMonitor": { "display": "always", "newline": "lf" }
}

Что здесь написано по-русски:

У нас есть ESP32, красный светодиод и резистор на 220 Ом.
Пин 13 ESP32 соединен с резистором. Резистор соединен с анодом светодиода. Катод светодиода соединен с землей (GND) ESP32.
Когда вы запустите код, который подает HIGH (1) на пин 13 — ток пойдет через резистор (чтобы не сжечь светодиод), зажжется светодиод и уйдет в землю. Цепь замкнута!

Обычно вы не редактируете этот файл руками. Wokwi делает это за вас, когда вы перетаскиваете детали мышкой.Но если вы захотите:

Скопировать чужой проект и быстро понять, как он собран.
Вручную исправить цвет провода или номинал резистора.
Добавить компонент, которого нет в графической палитре (редко, но бывает).
...тогда вы откроете этот файл и увидите четкую карту вашего устройства: «Какая ножка куда идет».

Структура элемента parts

Массив parts включает объекты, определяющие физические и виртуальные компоненты электронной схемы.

Каждый объект содержит уникальный идентификатор, класс устройства и набор конфигурационных параметров.

Среда сопоставляет идентификаторы с моделями драйверов симулятора и присваивает начальные состояния каждому элементу перед запуском эмуляции.

Ключ	Описание	Пример значения
`id`	Уникальный идентификатор компонента в схеме	`"board"`, `"res1"`, `"led1"`
`type`	Класс устройства в библиотеке Wokwi	`"wokwi-arduino-uno"`, `"wokwi-led"`, `"wokwi-resistor"`
`attrs`	Параметры компонента	`{ "color": "red", "value": "220" }`
`top`	Вертикальная координата размещения	`100`
`left`	Горизонтальная координата размещения	`200`
`rotate`	Угол поворота компонента в градусах	`0`, `90`, `180`, `270`

Описание поля type и библиотеки компонентов

Поле type определяет категорию устройства и связывает компонент с внутренним драйвером симуляции.

Библиотека компонентов включает микроконтроллеры, пассивные элементы, датчики, дисплеи и интерфейсы связи.

Платформа загружает соответствующий драйвер при парсинге конфигурации и применяет специализированные алгоритмы эмуляции для каждого класса устройств.

Категория	Значение поля type	Характеристика
Платы микроконтроллеров	`"wokwi-arduino-uno"`, `"wokwi-esp32-devkit-v1"`, `"wokwi-pi-pico"`	Инициализация вычислительного ядра и загрузка прошивки
Пассивные элементы	`"wokwi-resistor"`, `"wokwi-capacitor"`, `"wokwi-inductor"`	Моделирование сопротивления, ёмкости и индуктивности
Активные индикаторы	`"wokwi-led"`, `"wokwi-buzzer"`, `"wokwi-neopixel"`	Визуализация электрических сигналов и генерация акустических волн
Датчики и измерители	`"wokwi-dht22"`, `"wokwi-pir-motion-sensor"`, `"wokwi-potentiometer"`	Генерация аналоговых и цифровых сигналов окружающей среды
Дисплеи и интерфейсы	`"wokwi-ssd1306"`, `"wokwi-ili9341"`, `"wokwi-keypad"`	Отрисовка графических интерфейсов и обработка нажатий
Сетевые модули	`"wokwi-esp32-nvs"`, `"wokwi-w5500"`	Эмуляция сетевых стеков и протоколов передачи данных

Поле connections и правила трассировки

Массив connections описывает электрические связи между выводами компонентов через объекты с полями p1, p2 и дополнительными атрибутами оформления.

Среда интерпретирует пары идентификаторов выводов как проводники, вычисляет топологию цепи и применяет законы Кирхгофа для расчёта токов и напряжений в каждом такте симуляции.

Платформа поддерживает прямое соединение выводов, формирование шинных структур и параметризацию сопротивления проводников.

Ключ	Описание	Формат
`p1`	Идентификатор первого вывода	`"board:2"`, `"res1:1"`
`p2`	Идентификатор второго вывода	`"led1:A"`, `"board:GND"`
`color`	Цвет визуализации проводника	`"red"`, `"black"`, `"yellow"`
`curve`	Степень изгиба линии соединения	Числовое значение в процентах от 0 до 100

Поле dependencies и внешние модули

Массив dependencies содержит строковые идентификаторы внешних библиотек, загружаемых средой исполнения перед компиляцией проекта.

Система извлекает пакеты из репозиториев Arduino Library Manager или удалённых хранилищ исходного кода, разрешает вложенные зависимости и собирает объектные файлы.

Платформа линкует скомпилированные модули с основным кодом прошивки и передаёт результирующий бинарный файл виртуальному микроконтроллеру.

Формат строки	Назначение
`ИмяБиблиотеки`	Загрузка пакета из стандартного менеджера библиотек
`https://github.com/пользователь/репозиторий`	Загрузка исходного кода из удалённого репозитория
`ИмяБиблиотеки@версия`	Установка конкретного выпуска пакета
`git+https://ссылка`	Загрузка пакета через протокол Git

Пример конфигурации diagram.json

{
  "version": 1,
  "parts": [
    {
      "type": "wokwi-arduino-uno",
      "id": "board",
      "top": 0,
      "left": 0,
      "attrs": {}
    },
    {
      "type": "wokwi-resistor",
      "id": "res1",
      "top": 120,
      "left": 80,
      "attrs": { "value": "220" }
    },
    {
      "type": "wokwi-led",
      "id": "led1",
      "top": 200,
      "left": 120,
      "attrs": { "color": "red" }
    }
  ],
  "connections": [
    { "p1": "board:2", "p2": "res1:1", "color": "yellow" },
    { "p1": "res1:2", "p2": "led1:A", "color": "yellow" },
    { "p1": "led1:C", "p2": "board:GND", "color": "black" }
  ],
  "dependencies": []
}

Механизм обработки драйверов симуляции

Платформа связывает значение поля type с внутренним классом драйвера, реализующим методы инициализации, обновления состояния и обработки электрических сигналов.

Драйверы микроконтроллеров загружают двоичный код прошивки в виртуальную память, эмулируют тактирование ядра и воспроизводят реакцию периферийных блоков на входные сигналы.

Драйверы пассивных компонентов применяют дифференциальные уравнения электрических цепей для расчёта переходных процессов.

Драйверы индикаторов и дисплеев преобразуют цифровые уровни напряжения в визуальные эффекты и акустические параметры.

Система координирует работу всех драйверов через общую шину времени, синхронизирует обновление состояний в каждом такте симуляции и обеспечивает детерминированное воспроизведение поведения электронной схемы.

Справочник Wokwi