Wokwi: анатомия diagram.json — читаем файл схемы руками

Пять полей верхнего уровня

Откройте вкладку diagram.json в любом готовом примере Wokwi — наверху файла пять полей: version, author, editor, parts, connections. Первые три — служебная обвязка (номер формата, имя автора, метка редактора), а parts и connections — сама схема: что стоит на стенде и что с чем соединено. Дальше интереснее именно в них.

• version — номер формата файла; его пишут сервис и редактор, руками обычно не трогают.
• author — строка с именем автора проекта; на работу схемы не влияет, чистая подпись.
• editor — метка редактора, которым файл собран; тоже служебная.
• parts — массив деталей: плата, светодиод, резистор — каждый элемент описывает одну деталь стенда.
• connections — массив проводов: каждая строка — один физический провод между выводами двух деталей.

Деталь: type, id, attrs

{
  "version": 1,
  "author": "student",
  "editor": "wokwi",
  "parts": [
    { "type": "wokwi-arduino-uno", "id": "uno" },
    { "type": "wokwi-led", "id": "led1", "attrs": { "color": "red" } },
    { "type": "wokwi-resistor", "id": "r1", "attrs": { "value": "220" } }
  ],
  "connections": [
    [ "uno:13", "r1:1", "red", [] ],
    [ "r1:2", "led1:A", "red", [] ],
    [ "led1:C", "uno:GND.1", "black", [] ]
  ]
}

У каждой детали три поля. type — имя из каталога Wokwi: wokwi-arduino-uno, wokwi-led, wokwi-resistor; на момент проверки все имена несут префикс wokwi-. id — ваш личный ярлык детали: по нему провода находят её в connections, поэтому id обязаны быть уникальными. attrs — свойства: цвет светодиода, номинал резистора; у плат обычно пусто. Список живых типов и их attrs проще всего подсмотреть в diagram.json готового примера, а урок про структуру скетчбука заодно покажет, где у проекта вообще живут файлы.

Связь: массив из четырёх элементов

[ "uno:13",    "r1:1",  "red",   [] ],
[ "r1:2",      "led1:A", "red",   [] ],
[ "led1:C",    "uno:GND.1", "black", [] ]

Каждый провод — массив из четырёх элементов. Первый — вывод-источник в записи «id детали : имя пина»: uno:13 — цифровой пин 13, uno:A0 — аналоговый вход, uno:GND.1 — земля с номером разъёма. Второй — вывод-приёмник: led1:A — анод светодиода, led1:C — катод. Третий — цвет провода строкой: red, black, green. Четвёртый — служебный массив опций связи: в примерах он пустой, сервис заполняет его своими пометками. Правило чтения простое: «откуда : пин — куда : пин, цвет».

Когда файлом быстрее мыши

• Массовое переименование: сменили id led1 на led2 в двух местах — все провода переехали сами; мышкой перекинули бы каждый.
• Клонирование узла: пять одинаковых цепочек «резистор + светодиод» — пять копий блока parts и десять строк connections; на диаграмме — десятки щелчков.
• Аудит схемы: кто с кем соединён — виден построчно, без щелчков по каждому проводу.
• Перенос в другой проект: блоки parts и connections копируются целиком, схема переезжает между вкладками.
• История правок: файл в git показывает, какой провод добавили вчера; у диаграммы такого диффа нет.

Лаборатория выше гоняет меню Arduino IDE — и это не отступление: файлом вы правите схему, а всё остальное вокруг живёт в меню. «Файл → Сохранить», монитор порта, плоттер — привычки те же: правили diagram.json, перезапустили симуляцию, посмотрели в монитор. Меню в пальцах — правка файла идёт без пауз.

Грабли ручной правки

• Лишняя запятая после последнего элемента массива: JSON такого не прощает, файл перестаёт читаться целиком. Любой JSON-валидатор подсвечивает строку за секунду.
• Кавычки не те: скопировали текст из статьи с типографскими «ёлочками» — валидатор сыпется; в JSON живут только прямые двойные кавычки. Привычку чистить кавычки ставит урок про копирование кода из статей.
• Задвоенный id: две детали с одним id — провода вешаются на случайную из них; схема ведёт себя как попало, а файл выглядит складно.
• Несуществующий type: опечатались в имени детали — редактор откажется собирать; имя берите из каталога или готовых примеров, а не из памяти.
• Пин, которого нет: led1:D у светодиода не существует — есть A и C; uno:GND без номера тоже не пройдёт, земля нумеруется по разъёмам.

Мышь против файла: кто когда

Формат живой: поля и имена деталей выше сверены с живыми примерами на момент проверки, но сервис развивается — новые детали приносят новые attrs, список типов растёт, и гарантий обратной совместимости никто не даёт. Перед массовой правкой сделайте копию файла и проверьте её на свежем примере; первоисточник один — официальная документация Wokwi. А если нужен стенд, где схема собирается сама из скетча, — наш симулятор вешает детали и провода по коду, лендинг про него расскажет, что он умеет.

Частые вопросы