Документация и инструменты для запуска fsm32

1. Базовая идея

Программа описывает начальное состояние, условия перехода и действия на выходах. Логика выполняется циклически: система фиксирует входы, исполняет правила и обновляет выходы.

codename HomeLight;
#include <ESP32-C3-MINI.hw>

fsm LightControl : Button {
  initial state Idle : Button {
    if (Button == true) {
      STATE(Active);
    }
  }
}

2. Синтаксис языка (EBNF)

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

program ::= codename_decl include_directive*
            common_decl*
            in_services_block?
            unused_block?
            init_block?
            (fsm_decl | stateless_decl)+

codename_decl ::= "codename" identifier ";"
include_directive ::= "#include" "<" include_path ">"

fsm_decl ::= [ "unsafe" ] "fsm" identifier [ ":" trigger_list ] "{"
               { on_overflow_block | out_services_block | state_decl }
             "}"

state_decl ::= [ "initial" ] "state" identifier [ ":" watch_list ] "{"
                 { statement }
               "}"

Идентификатор начинается с буквы; далее допускаются буквы, цифры, _ и .. Однострочный комментарий начинается с //.

Типы

bool, int8, uint8, int16, uint16, int32, uint32, float, bit.

Операторы

=, ==, !=, <, >, <=, >=, !, &&, ||, +, -, *, /, %, <<, >>, &, |, ^, ~, =>.

Директивы

#include <File.hw> подключает аппаратный каталог; #hardware_profile Name задаётся только внутри .hw и должен совпадать с идентификатором профиля в firmware контроллера.

3. Каталог ключевых слов, операторов и функций

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

4. Темы и примеры использования

Каждая тема раскрывает конструкцию из каталога: имя, синтаксис, назначение и минимальный рабочий контекст.

codename HomeLight;
#include <ESP32-C3-MINI.hw>

fsm Control { ... }

#hardware_profile ESP32-C3-MINI
out bool StatusLed;
in bool BootButton;

// В .fsmc:
unused { StatusLed; }

common uint16 Attempts;
in_services { in bool Command; }
out_services { bool IsActive; }
init {
  Attempts = 0;
  IsActive = false;
}

fsm LightControl : Button {
  initial state Idle {
    if (Button) { STATE(Active); }
  }
}

stateless Mirror : any {
  IsActive = Command;
}

fsm Monitor : any {
  initial state Observe {
    IsActive = Command;
  }
}

unsafe fsm FastPath {
  initial state Run {
    Counter = Counter + 1;
  }
}

fsm Guard {
  ON_Overflow {
    Fault = true;
    STATE(Error);
  }
}

initial state Idle : Button {
  Lamp = false;
}
state Active : Button {
  Lamp = true;
}

if (Button == true) {
  STATE(Active);
}

Relay = Command;
STABILIZE;
Ready = Relay;

if (Pressure >= Minimum) {
  Pump = true;
} else {
  Pump = false;
}

do {
  Count = Count + 1;
} while (Count < 3);

for (Index = 0; Index < 3; Index = Index + 1) {
  Total = Total + Index;
}

while (Count < Limit) {
  if (Stop) { break; }
  Count = Count + 1;
  if (!Enabled) { continue; }
  Total = Total + Count;
}

await(Button => Button == true);
Lamp = true;
STATE(Active);

waitfor(5000, Pressure => Pressure == true, Error);
Pump = true;

state Error {
  Alarm = true;
}

Lamp = true;
sleep(1000);
Lamp = false;

Enabled = true;
if (Enabled == false) {
  STATE(Idle);
}

Setpoint = Target + Offset;
Ready = Pressure >= Minimum;

if (Temperature >= Limit) {
  Alarm = true;
}
if (Mode != PreviousMode) {
  Changed = true;
}

if (!Fault && Enabled) {
  Pump = true;
}
if (Stop || Timeout) {
  STATE(Error);
}

Average = Sum / Count;
Remainder = Total % 10;
Scaled = Raw * Factor + Offset;

Mask = Mask << 1;
Flags = (Flags | 1) & 255;
Inverted = ~Flags;

Scaled = (Raw + Offset) * Factor;
// Без скобок: Raw + (Offset * Factor)

Required = CEIL(Voltage);
if (Required > Limit) {
  Alarm = true;
}

LowerBound = FLOOR(Voltage);
Status = LowerBound >= Minimum;

DisplayValue = ROUND(Voltage);
Output = DisplayValue * Scale;

4. Структура программы и объявления

codename

Имя программы или узла.

#include <Profile.hw>

Подключает каталог аппаратных сервисов выбранного профиля платы.

in_services / out_services

Объявляют логические входы и выходы.

fsm

Объявляет конечный автомат с набором состояний.

5. Состояния и переходы

state задаёт режим работы. Переход выполняется через STATE, когда выполнено условие.

state Active : Button {
  Lamp = true
  if (Button == false) {
    STATE(Idle);
  }
}

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

6. Автоматы, trigger/watch и защита вычислений

После имени fsm или state можно задать список сигналов через двоеточие. У fsm это trigger, у state — watch: изменение элемента списка активирует автомат или перезапускает состояние. В списке допустимы in- и common-сервисы; без списка блок запускается в каждом проходе стабилизации. any и all эквивалентны, означают все in-сервисы и не совмещаются с именованными элементами.

common uint16 Attempts;

fsm Guard : Button, Pressure {
  ON_Overflow {
    STATE(Error);
  }

  initial state Idle : Button {
    if (Button == true) {
      Attempts = Attempts + 1;
      STATE(CheckPressure);
    }
  }
}

stateless подходит для простого реактивного преобразования сигналов. В нём недоступны STATE, STABILIZE, await, waitfor и sleep. Используйте unsafe только если осознанно отключаете для блока checked-ветки overflow/div0 и compile-time narrowing.

7. Управляющие конструкции

Условия и циклы используют круглые скобки для условия, а фигурные — для тела блока. break и continue применяются внутри циклов.

for (Index = 0; Index < 3; Index = Index + 1) {
  if (!Enabled) {
    break;
  }

  if (Index == 1) {
    continue;
  }

  Total = Total + Index;
}

Циклы выполняются в рамках логики автомата; не используйте их как замену ожиданию внешнего события. Для событий и задержек применяйте await, waitfor и sleep.

8. Ожидания и таймеры

await(Signal => condition|any)

Приостанавливает FSM, ожидая выполнения условия либо изменения in/common-сервиса.

waitfor(timeout, Signal => condition|any, TimeoutState)

Ожидает условие с контролируемым таймаутом и при истечении автоматически переходит в указанный state.

sleep(milliseconds)

Приостанавливает FSM; время квантуется VM tick в 100 мс и округляется вверх.

ON_Overflow

Определяет реакцию на арифметический overflow, деление и остаток от деления на ноль.

waitfor(5000, Pressure => Pressure == true, Error);
Pump = true;

state Error {
  Alarm = true;
}

9. Выражения и операторы

Арифметика, сравнения и логические операторы образуют выражения в присваиваниях и условиях. Скобки меняют порядок числовых вычислений. Побитовые операции &, |, ^, ~ и сдвиги <<, >> допустимы только для беззнаковых типов.

Scaled = (Raw + Offset) * Scale;
Flags = (Flags | 1) & 255;

if ((Pressure >= Minimum) && !Fault) {
  Ready = true;
}

Приоритет: скобки и унарные операции → умножение/деление/остаток → сдвиги → сложение/вычитание → побитовые операции → сравнения → && → ||.

10. Числовые функции

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

WholeUp = CEIL(Reading);
WholeDown = FLOOR(Reading);
Nearest = ROUND(Reading);

CEIL(x)

Округляет x вверх.

FLOOR(x)

Округляет x вниз.

ROUND(x)

Округляет x до ближайшего целого.

11. Аппаратные профили

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

Важно: FSMC управляет логикой устройства; пакет .fsmb не является прошивкой ESP-IDF. Firmware и пакет логики обновляются разными процессами.

12. Следующий шаг

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