Объяснение основных конструкций языка Rust.

#![no_main]

Это директива компилятора (атрибут), который говорит компилятору Rust: "В этой программе нет стандартной функции main, используемой как точка входа".

Ключевые особенности:

1. Запрещает стандартную точку входа в программу (standard main() entry point. Обычно программы Rust начинают свое выполнение в fn main(). Директива #![no_main] говорит компилятору, что не нужно ожидать в коде или генерировать обычный код настройки функции main.

2. Обычно используется в специальном рабочем окружении:

• Встраиваемые системы (например приложения микроконтроллера ESP32) - там где вам нужен специальный пользовательский код запуска (custom startup code).
• Ядра операционных систем - пользовательские процессы загрузки (custom boot processes).
• "Bare-metal" программирование - приложение без операционной системы.
• Пользовательская среда выполнения (custom runtime environment) - где какой-то другой код обрабатывает начальную инициализацию. Например, это может быть код отдельного модуля/субмодуля, см. Q003 []).

3. Обычно используется совместно другими атрибутами:

#![no_std]       // используется модель приложения без стандартной библиотеки
#![no_main]      // не используется стандартная функция main

4. Требуется пользовательская точка входа (custom entry point): нужно определить вашу собственную функцию, обычно с такими атрибутами:

#[entry]         // Часто применяются в embedded Rust (например RTIC, embassy)
#[no_mangle]     // Предотвращает изменение имен (name mangling)
pub extern "C" fn main() -> ! {
    // Ваша точка входа в программу:
    loop {}
}

Или:

#[esp_hal_embassy::main]
async fn main(spawner: Spawner) {
   ...

Пример использования в программе без операционной системы (bare-metal embedded program):

#![no_std]
#![no_main]

use cortex_m_rt::entry;
use panic_halt as _;

#[entry]
fn main() -> ! {
    // Пользовательский код инициализации:
    setup_peripherals();

    // Бесконечный цикл программы приложения:
    loop {
        application_logic();
    }
}

Разработка OS kernel:

#![no_std]
#![no_main]

#[no_mangle]
pub extern "C" fn _start() -> ! {
    // Инициализация kernel:
    early_init();

    // Kernel main loop:
    loop {}
}

Когда используется или не используется #![no_main]:

Важные замечания:

• Не для обычных приложений - используется только в специальных рабочих окружениях
• Требует пользовательского кода (custom runtime) - вы отвечаете за инициализацию приложения
• Обычно используется вместе с атрибутом #![no_std] - в большинстве случаев приложения микроконтроллеров не используют стандартную библиотеку
• Зависит от специфики платформы - реальное имя точки входа или соглашения о её оформлении зависит от целевой системы (target)

В заключение: #![no_main] говорит "Сам разберусь с запуском программы, спасибо" - для случая, когда вам нужно полностью управлять началом выполнения вашей программы.

#![no_std]

Это фундаментальный атрибут, который говорит компилятору Rust: "Этот крейт не использует стандартную библиотеку Rust".

Ключевые последствия:

1. Недоступна стандартная библиотека.

• Нет std:: модулей (наподобие std::vec::Vec, std::string::String)
• Нет кучи (если вы специально не вставите allocator)
• Нет файловой системы, поддержки сети, или специфичного для OS функционала
• Нет стандартных thread, mutex или других примитивов синхронизации

2. Вы все еще получите:

• Core library (core::) - базовые типы, трейты (traits) и функции, такте как:

core::option::Option, core::result::Result
core::mem, core::slice, core::str
Трейты наподобие Copy, Clone, Debug

• Поддержку компилятора (compiler built-ins) - базовые фичи языка

3. Вы сами должны предоставить:

• Динамическое выделение памяти (если нужна куча)
• Обработчик паники (panic handler)
• Код первоначального запуска (startup code)
• Поддержку ввода/вывода (IO facilities)

Пример базовой no_std-программы без кучи:

#![no_std]
#![no_main]

// Необходимо: определяет panic handler
use core::panic::PanicInfo;

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {} // Custom panic behavior
}

// Entry point (зависит от платформы)
#[no_mangle]
pub extern "C" fn _start() -> ! {
    // Здесь начинается ваш код, библиотека stdlib недоступна:
    loop {}
}

Если нужен allocator (нужна куча):

#![no_std]
extern crate alloc;  // вставка использования крейта alloc

use alloc::vec::Vec;
use alloc::string::String;

// Определение глобального выделителя памяти:
#[global_allocator]
static ALLOCATOR: some_allocator::MyAllocator = some_allocator::MyAllocator;

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}

...

Где обычно используется #![no_std]:

1. Встраиваемые системы

#![no_std]#![no_main]
use cortex_m_rt::entry;

#[entry]
fn main() -> ! {
    // Прямой доступ к аппаратуре:
    unsafe { (*0x4000_0000).write(0x42) };
    loop {}
}

2. Ядра операционных систем (OS kernels)

#![no_std]
#![no_main]

#[no_mangle]
pub extern "C" fn _start() -> ! {
    // Инициализация памяти, прерываний, и т. д.
    kernel_init();
    loop {}
}

3. WebAssembly без stdlib

#![no_std]

#[no_mangle]
pub extern "C" fn add(a: i32, b: i32) -> i32 {
    a + b  // чистое вычисление, std не требуется
}

4. Bootloader-ы и firmware

#![no_std]
#![no_main]

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    // Сброс системы вместо обработки паники
    // с выдачей описания ошибки:
    reset_cpu();
}

Что вы теряете без std:

Что у вас останется вместе с core:

Типовая структура приложения:

#![no_std]
#![no_main]

// 1. Panic handler (требуется)
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    // Пользовательская реализация обработчика паники
    loop {}
}

// 2. Опционально: allocator (если нужна heap)
#[global_allocator]
static ALLOCATOR: MyAlloc = MyAlloc;

// 3. Опционально: элементы языка (редко используется)
#[lang = "eh_personality"]
extern "C" fn eh_personality() {}

// 4. Точка входа (Entry point)
#[no_mangle]
pub extern "C" fn _start() -> ! {
    // Код вашего приложения
    loop {}
}

В заключение: #![no_std] предназначен для случаев, когда вы работаете в средах, где предположение о наличии стандартной библиотеки (о наличии ОС, выделении памяти и т. д.) не соответствуют действительности. Это дает вам полный контроль над кодом, но требует, чтобы вы предоставили все, что обычно дает стандартная библиотека.

#![deny(clippy::mem_forget)]

Атрибут #![deny(clippy::mem_forget)] это линт-директива, которая инструктирует Clippy linter обрабатывать любое использование std::mem::forget как ошибку.

Примечание: linter это процесс обработки кода программы, который анализирует код на наличие потенциальных ошибок. Clippy linter [1] это набор линт-директив для перехвата общих промахов в программировании, что позволяет улучшить ваш код Rust.

#![deny(...)]: это стандартный атрибут Rust, который устанавливает уровень lint-ов, заключенных в скобки на "deny", т. е. запрет. Это означает, что если указанные линты сработают, то компиляция завершится с сообщением об ошибке.

clippy::mem_forget: это относится к проверке на наличие вызова std::mem::forget. Если такой вызов будет обнаружен, то будет выведено сообщение об ошибке reason.

Таким образом, #![deny(clippy::mem_forget)] дает следующие преимущества:

1. Предотвращаются утечки памяти. Библиотеки, где используется Drop, всегда будут правильно выполнять очистку переменных и буферов.
2. Повышается безопасность кода. Снижается риск связанных с памятью проблем для случаев, когда неправильно организовано управление ресурсами.
3. Поощряется явное управление ресурсами: способствует использованию более безопасных и более идиоматических моделей кода Rust для управления ресурсами.

Пример использования:

#![deny(
    clippy::mem_forget,
    reason = "Использование mem::forget обычно небезопасно с типами esp_hal, \
              особенно с теми, что удерживают буферы в течение передачи данных."
)]

use core::{i32, u16};

Эта строчка делает следующее:

• Импортирует примитивные типы i32 и u16 из библиотеки core в текущую область видимости кода
• Делает эти типы доступными для использования без необходимости добавлять к ним префикс core::

Типы:

i32: 32-разрядное число со знаком (диапазон значений: -2147483648 .. 2147483647)
u16: 16-разрядное число без знака (диапазон значений: 0 .. 65535)

Почему это используют:

1. Переменные такого типа входят в подмножество типов стандартной библиотеки, для которых не требуется специальная процедура выделения памяти или зависимость от OS.
2. Полезно для применения в проектах с моделью no_std (встраиваемые системы, разработка OS и т. п.), где требуется работа с ресурсами на низком уровне.
3. В обычном использовании Rust (с моделью std) эти типы доступны автоматически без префикса, так что такой импорт не требуется.

use core::{i32, u16};

// После этой директивы импорта вы можете использовать:
let x: i32 = 42;
let y: u16 = 1000;

// .. вместо следующих конструкций:
let x: core::i32 = 42;
let y: core::u16 = 1000;

use defmt::info;

Эта директива импортирует макрос вывода в лог из крейта defmt, специально разработанного для встраиваемых приложений (микроконтроллеров). Директива делает следующее:

• Импортирует макрос info! из крейта defmt в текущую область видимости кода
• Позволяет использовать info!(...) вместо defmt::info!(...)

Ключевые характеристики defmt:

• Очень эффективный, структурированный фреймворк лога для встраиваемых устройств
• Намного меньше расходует память чем традиционный println! крейта log
• Поддерживает двоичный формат, который требует декодирования на стороне хоста (использование defmt-print)
• Устраняет во время компиляции не используемые строки формата

Пример использования:

use defmt::info;

fn main() {
    let temperature = 25.5;
    let status = "ok";

    info!("Температура: {}°C, Статус: {}", temperature, status);
    // На хосте: defmt-print target/device.log
    // Вывод: Температура: 25.5°C, Статус: ok
}

Сравнение с другими вариантами вывода в лог::

• println!: стандартный тяжелый вывод, требует полной поддержки модели std
• log::info!: более структурированное API, но все еще очень требовательное к ресурсам
• defmt::info!: оптимизированный лог для встраиваемых систем, с минимальными тратами runtime-ресурсов

Типовой процесс использования:

1. Устройство выводит сообщения вызовами defmt::info!
2. Логи сохраняются в двоичном формате
3. Компьютер хоста декодирует формат лога с помощью утилиты defmt-print

Импорт defmt::info особенно важен для эффективной отладки и мониторинга систем с ограниченными ресурсами, где традиционный вывод в лог текста оказывается слишком дорогим решением.

use embassy_executor::{task, Spawner};

Импортирует ключевые компоненты из Embassy executor для асинхронного (на основе потоков) программирования. Импортируется следующее:

1. Макрос атрибута task

#[task]
async fn my_task() {
    // Код асинхронной задачи
}

• Декларируется асинхронная функция как Embassy task
• Задачи (tasks) в Embassy представляют фундаментальные единицы выполнения

2. Тип Spawner

let spawner: Spawner = /* извлекается из executor */;

• Используется для запуска задач (tasks) и управления ими runtime
• Позволяет динамически порождать асинхронные задачи

Пример, как это работает:

use embassy_executor::{task, Spawner};

// Декларация функции задачи
#[task]
async fn blink_led() {
    // Код, мигающий светодиодом
}

// Другая задача, которая использует spawner
#[task]
async fn main_task(spawner: Spawner) {
    // Порождение задачи blink_led
    spawner.spawn(blink_led()).unwrap();

    // Другая асинхронная работа ...
}

Ключевые концепции Embassy:

• Executor: облегченная среда асинхронного runtime для встраиваемых систем
• Tasks: асинхронные функции, которые работают одновременно и конкурентно, разделяя общее процессорное время
• Spawner: механизм для динамического запуска задач
• Без выделения памяти в куче: разработано для bare-metal рабочей среды

Типовая схема применения:

1. Определяются задачи как функции с атрибутом #[task]
2. Получение Spawner из настройки executor
3. Использование spawner.spawn() для запуска задач
4. Embassy обслуживает планировку и выполнение кода задач (scheduling)

Импорт embassy_executor::{task, Spawner} это фундаментальный метод построения асинхронных встраиваемых приложений в среде Embassy, предоставляющий эффективное конкурентное выполнение функций без OS threads, и чрезмерного расхода ресурсов runtime.

use embassy_time::{Delay, Duration, Ticker, Timer};

Импортирует утилиты для обработки времени из Embassy embedded async framework.

Что делает каждый из импортируемых компонентов:

1. Duration

let delay_time = Duration::from_millis(500);

• Представляет интервалы времени (миллисекунды, секунды, и т. д.)
• Используется для указания интервалов времени

2. Delay

let mut delay = Delay;
delay.sleep(Duration::from_secs(1)).await;

• Простая однократная задержка выполнения
• Блокирует асинхронное выполнение на указанную длительность

3. Timer

Timer::after(Duration::from_millis(100)).await;
// или:
Timer::after_millis(100).await;

• Однократный таймер, который сработает после указанной длительности
• Более удобный, чем Delay, для одиночных ожиданий

4. Ticker

let mut ticker = Ticker::every(Duration::from_secs(1));
loop {
    ticker.next().await;
    // Выполняется каждую секунду
}

• Периодичный таймер, срабатывающий с регулярными интервалами
• Полезен для периодического выполнения задач (опроса сенсоров, мигание светодиодами и т. д.)

Пример мигания светодиодом:

use embassy_time::{Duration, Timer};

#[task]
async fn blink_led() {
    loop {
        led.set_high();
        Timer::after_millis(500).await;
        led.set_low();
        Timer::after_millis(500).await;
    }
}

Пример периодического опроса датчика:

use embassy_time::{Duration, Ticker};

#[task]
async fn read_sensor() {
    let mut ticker = Ticker::every(Duration::from_secs(5));
    loop {
        ticker.next().await;
        let reading = sensor.read().await;
        info!("Sensor: {}", reading);
    }
}

Ключевые особенности:

• Async-aware: все методы имеют функцию .await
• Нет busy-waiting: эффективно уступаются ресурсы процессора для других задач
• Hardware-backed: использует аппаратные таймеры при их наличии
• Zero-cost: минимальные накладные расходы ресурсов (runtime overhead)

Импорт embassy_time::{Delay, Duration, Ticker, Timer} особенно важен для организации интервалов времени, задержек и периодических операций для программирования асинхронных приложений с использованием Embassy.

use esp_hal::analog::adc::{Adc, AdcCalBasic, AdcCalScheme, AdcChannel, AdcConfig, Attenuation};

Импортирует компоненты ADC (Analog-to-Digital Converter) из библиотеки ESP-HAL (Hardware Abstraction Layer) микроконтроллеров ESP.

Что делает каждый компонент:

1. Adc - представляет основное периферийное устройство АЦП

let mut adc = Adc::new(peripherals.ADC1, config);

• Обеспечивает первичный интерфейс к контроллеру ADC
• Обслуживает операции и преобразования ADC

2. AdcConfig - конфигурация ADC

let config = AdcConfig::new();

• Настраивает параметры ADC (разрешающая способность, тактирование и т. п.)
• Используется для конфигурирования периферийного устройства ADC

3. AdcChannel - входной канал ADC

let mut pin = gpio_pin.into_analog();

• Представляет определенный вход ADC (вывод корпуса/канал)
• Используемые выводы должны быть сконфигурированы как аналоговые входы

4. Attenuation - масштабирование чувствительности по входу

let config = AdcConfig::new().attenuation(Attenuation::Attenuation11dB);

Позволяет управлять диапазоном оцифровки входного напряжения:

Attenuation::Attenuation0dB   ≈ 0-1.1V
Attenuation::Attenuation2_5dB ≈ 0-1.5V
Attenuation::Attenuation6dB   ≈ 0-2.2V
Attenuation::Attenuation11dB  ≈ 0-3.9V

5. AdcCalBasic/AdcCalScheme - калибровка

let adc_cal = AdcCalBasic::new();

• Предоставляет подпрограммы калибровки ADC
• Компенсирует погрешности аппаратуры
• Повышает точность измерений

Типовой пример использования:

use esp_hal::analog::adc::{Adc, AdcCalBasic, AdcConfig, Attenuation};
use esp_hal::gpio::Analog;

#[task]
async fn read_adc(mut adc_pin: AnalogPin) {
    let config = AdcConfig::new()
        .attenuation(Attenuation::Attenuation11dB);
        let mut adc = Adc::new(peripherals.ADC1, config);
    let adc_cal = AdcCalBasic::new();

    loop {
        let reading: u16 = adc.read(&mut adc_pin, &adc_cal).unwrap();
        info!("ADC reading: {}", reading);

        Timer::after_millis(100).await;
    }
}

Ключевые особенности:

• Учитывает специфику микроконтроллеров Espressif: оптимизация для ESP32, ESP32-C3, ESP32-S3 и т. п.
• Предоставляет абстракцию от аппаратуры: обеспечивает универсальный интерфейс программирования для различных вариантов микроконтроллеров ESP
• Поддержка калибровки: встроенная компенсация нелинейностей ADC
• Async-ready: разработано с учетом работы в среде асинхронного выполнения наподобие Embassy

Импорт esp_hal::analog::adc::{Adc, AdcCalBasic, AdcCalScheme, AdcChannel, AdcConfig, Attenuation}; важен для чтения аналоговых датчиков (потенциометров, термопар, фотодатчиков, и т. д.) на микроконтроллерах ESP.

use esp_hal::gpio::{AnalogPin, Output, OutputConfig, Level};

Импортирует компоненты GPIO (General Purpose Input/Output) из ESP-HAL для микроконтроллеров ESP.

Что делает каждый компонент:

1. Output - тип вывода, настроенного на выход

let mut led_pin = gpio_pin.into_output();

• Конфигурирует ножку порта GPIO как цифровой выход
• Может программно управлять выходным цифровым сигналом (high или low, т. е. лог. 1 или лог. 0)

2. AnalogPin - тип вывода, настроенного как аналоговый вход

let mut adc_pin = gpio_pin.into_analog();

• Конфигурирует ножку порта GPIO как аналоговый вход
• Применяется для входа ADC (Analog-to-Digital Converter)

3. OutputConfig - конфигурация выхода

let config = OutputConfig::default()
    .drive_strength(DriveStrength::High);

Конфигурирует поведение выходного вывода порта:

• Нагрузочная способность (возможности по выходному току)
• Открытый сток (open-drain) или двухтактный ключ (push-pull)
• Начальный выходной логический уровень

4. Level - цифровой уровень логики

led_pin.set_high();    // Level::High
led_pin.set_low();     // Level::Low

Представляет состояния логического сигнала:

Level::High (3.3V на ESP)
Level::Low (0V)

Пример использования для цифрового вывода (светодиод LED):

use esp_hal::gpio::{Output, Level};

#[task]
async fn blink_led(mut led_pin: OutputPin) {
    loop {
        led_pin.set_high();
        Timer::after_millis(500).await;
        led_pin.set_low();
        Timer::after_millis(500).await;
    }
}

Пример использования для аналогового входа (ADC):

use esp_hal::gpio::{AnalogPin, Output};
use esp_hal::analog::adc::{Adc, AdcConfig};

#[task]
async fn read_sensor(mut sensor_pin: AnalogPin) {
    let mut adc = Adc::new(peripherals.ADC1, AdcConfig::new());

    loop {
        let reading = adc.read(&mut sensor_pin).unwrap();
        info!("Sensor: {}", reading);
        Timer::after_millis(100).await;
    }
}

Конфигурируемый выход:

use esp_hal::gpio::{Output, OutputConfig, Level};

let config = OutputConfig::default()
    .drive_strength(DriveStrength::High)
    .initial_level(Level::Low);

let mut motor_pin = gpio_pin.into_output_with_config(config);

Ключевые особенности:

• Учитывается специфика ESP: оптимизировано для микроконтроллеров серии ESP32
• Type-safe: предотвращает неправильную конфигурацию (аналоговый вывод нельзя использовать как цифровой выход)
• Гибкое конфигурирование: различные нагрузочные способности и режимы
• Низкоуровневое управление: прямой доступ к аппаратуре без гарантий безопасности

Импорт esp_hal::gpio важен для управления цифровыми выходами и входами (светодиоды, моторы, реле, кнопки) и конфигурирования аналоговых входов (сенсоров) на микроконтроллерах ESP.

use esp_hal::{peripherals, Async};

Импортирует два фундаментальных компонента из ESP-HAL, позволяющих работать с микроконтроллерами ESP в асинхронных контекстах.

1. peripherals - доступ к аппаратным периферийным устройствам

let peripherals = peripherals::Peripherals::take().unwrap();

• Предоставляет безопасный доступ ко всей аппаратной периферии (GPIO, ADC, SPI, I2C, UART и т. д.)
• Использует систему владения (Rust ownership system) для предотвращения конфликтов конкурентного доступа
• Возвратит структуру Peripherals, содержащую все доступные аппаратные интерфейсы

Пример использования:

let peripherals = peripherals::Peripherals::take().unwrap();
let pins = peripherals.GPIO;
let adc1 = peripherals.ADC1;
let uart0 = peripherals.UART0;

2. Async - маркер асинхронного режима

let mut led = pins.gpio2.into_output().into_async();

• Тип нулевого размера, который помечает периферийное устройство как используемого для асинхронных операций.
• Преобразует функции периферии с блокировкой в их версии, совместимые с асинхронным контекстом
• Разрешает функционал .await на операциях с аппаратурой

Пример использования:

use esp_hal::{peripherals, Async};

#[main]
async fn main(spawner: Spawner) {
    let peripherals = peripherals::Peripherals::take().unwrap();
    let pins = peripherals.GPIO;

    // Преобразование вывода в async-режим
    let mut led = pins.gpio2.into_output().into_async();

    // Теперь мы можем использовать асинхронно отслеживаемые
    // интервалы задержек (с освобождением runtime-контекста
    // для других задач):
    loop {
        led.set_high();
        Timer::after_millis(500).await;
        led.set_low();
        Timer::after_millis(500).await;
    }
}

Типовой шаблон настройки:

use esp_hal::{peripherals, Async};

#[main]
async fn main() {
    // Взятие во владение (ownership) всех периферийных устройств
    let peripherals = peripherals::Peripherals::take().unwrap();

    // Инициализация системных компонентов
    let system = peripherals.SYSTEM.split();

    // Конфигурирование тактирования
    let clocks = ClockControl::max(system.clock_control).freeze();

    // Инициализация async executor
    let executor = EmbassyExecutor::new();
    executor.run(|spawner| {
        spawner.spawn(main_task(peripherals)).unwrap();
    });
}

#[task]
async fn main_task(peripherals: Peripherals) {
    let pins = peripherals.GPIO;
    let mut led = pins.gpio2.into_output().into_async();
    // Async-операции...
}

Ключевые особенности:

• Обеспечивает безопасный доступ к периферийным устройствам: предотвращает аппаратные конфликты во время компиляции
• Интеграция асинхронного функционала: позволяет выполнять операции с аппаратурой без блокировки выполнения
• Учитывает специфику ESP: оптимизировано для семейства микроконтроллеров ESP
• Абстракция с нулевыми затратами: минимальные накладные расходы (runtime overhead)

Импорт esp_hal::{peripherals, Async} важен для любых асинхронных встраиваемых приложений на чипах ESP, что предоставляет защищенный доступ как к аппаратуре, так и к async-функционалу.

use esp_hal::{clock::CpuClock, gpio::Input, gpio::InputConfig};

Импортирует компоненты для конфигурации тактирования и обработки входов GPIO из библиотеки ESP-HAL.

Что делает каждый компонент:

1. clock::CpuClock - конфигурация частоты тактирования CPU

let clocks = ClockControl::configure(
    system.clock_control,
    CpuClock::Clock240MHz,  // установит CPU на частоту 240 МГц
    // другие настройки тактирования...
).freeze();

• Управляет частотой тактов CPU микроконтроллеров ESP. Доступны опции:

CpuClock::Clock80MHz
CpuClock::Clock160MHz
CpuClock::Clock240MHz

• Влияет на производительность и энергопотребление

2. gpio::Input - определяет вывод как вход

let button = gpio_pin.into_input();

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

3. gpio::InputConfig - конфигурация входа

let config = InputConfig::default()
    .pull_up(true)      // разрешает внутренний pull-up резистор
    .pull_down(false);  // запрещает внутренний pull-down резистор

Позволяет конфигурировать поведение вывода порта входа:

• Активация/деактивация внутренних pull-up/pull-down резисторов
• Фильтрация выбросов входного сигнала (glitch filtering)
• Настройки прерываний

Пример конфигурации тактирования:

use esp_hal::{clock::CpuClock, peripherals};

let peripherals = peripherals::Peripherals::take().unwrap();
let system = peripherals.SYSTEM.split();

// Конфигурирует CPU на максимальную скорость (240 МГц)
let clocks = ClockControl::configure(
    system.clock_control,
    CpuClock::Clock240MHz,
    // Другие домены тактирования...
).freeze();

Пример опроса кнопки с замыканием на землю и использованием pull-up:

use esp_hal::gpio::{Input, InputConfig};

#[task]
async fn read_button(mut button_pin: InputPin) {
    let config = InputConfig::default()
        .pull_up(true);  // разрешение внутреннего резистора pull-up

    let button = button_pin.into_input_with_config(config);

    loop {
        if button.is_low() {
            info!("Нажата кнопка!");
        }
        Timer::after_millis(10).await;
    }
}

Пример пользовательского конфигурирования ввода:

use esp_hal::gpio::{Input, InputConfig};

// Конфигурация входа с внутренним резистором pull-down и фильтрацией
let config = InputConfig::default()
    .pull_up(false)
    .pull_down(true)      // разрешение pull-down резистора
    .glitch_filter(true); // разрешение фильтрации шума

let sensor_input = gpio_pin.into_input_with_config(config);

Ключевые особенности:

• Управление производительностью: CpuClock позволяет выбрать баланс между скоростью и потреблением тока
• Гибкая конфигурация входа: управление встроенными резисторами подтяжки (pull-up, pull-down), фильтрация помех, поддержка прерываний
• Оптимизация поддержки аппаратуры: реализация, учитывающая специфику микроконтроллеров ESP
• Type-safe: предотвращает неправильную конфигурацию во время компиляции

Импорт esp_hal::{clock::CpuClock, gpio::Input, gpio::InputConfig} важен для настройки частоты тактирования микроконтроллера ESP и чтения цифровых сигналов наподобие кнопок, переключателей или цифровых датчиков.

use esp_hal::timer::systimer::SystemTimer;

Импортирует периферийное устройство System Timer (SYSTIMER) из библиотеки ESP-HAL. SystemTimer это периферийное устройство выделенного системного таймера, имеющегося на кристалле микроконтроллеров ESP. Этот таймер предоставляет следующие ключевые возможности:

• 64-битный счетчик с высокой разрешающей способностью
• Не зависит от тактовых сигналов основного CPU
• Возможность работы низкого энергопотребления
• Несколько alarm-компараторов для генерации прерываний

Пример точного измерения интервалов времени:

use esp_hal::timer::systimer::SystemTimer;

let systimer = SystemTimer::new(peripherals.SYSTIMER);

let start = systimer.now();
// Выполнение какого-то кода
let end = systimer.now();
let elapsed = end - start;
info!("Время выполнения: {} тактов", elapsed);

Пример микросекундных задержек:

use esp_hal::timer::systimer::SystemTimer;

fn delay_us(microseconds: u64) {
    let systimer = SystemTimer::new(peripherals.SYSTIMER);
    let start = systimer.now();
    while systimer.now() - start < microseconds * 40 { // Подстройте под частоту тактов
        // Busy wait - блокирующее ожидание
    }
}

Тайминг async executor:

use esp_hal::timer::systimer::SystemTimer;

// Часто используется внутри кода async executors наподобие Embassy
// для планировщика задач (task scheduling) и управления временем

Преимущества в сравнении с другими таймерами:

• Выше точность, чем у обычных (general-purpose) таймеров
• Продолжает работать в режимах пониженного энергопотребления (sleep modes) - полезная фича для приложений, критичных для экономии потребляемого тока
• Выделенная аппаратура, которая не используется для других функций

Типовая инициализация:

use esp_hal::{peripherals, timer::systimer::SystemTimer};

let peripherals = peripherals::Peripherals::take().unwrap();
let systimer = SystemTimer::new(peripherals.SYSTIMER);

// Использование для точного отсчета времени
let timestamp = systimer.now();

Импорт esp_hal::timer::systimer::SystemTimer необходим для отсчета времени высокой точности, анализа производительности выполняемого кода, низкоуровневого управления временем на микроконтроллерах ESP, особенно когда приложение критично к точности отсчета времени.

use {esp_backtrace as _, esp_println as _};

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

1. esp_backtrace as _

• Импортирует и инициализирует функционал обратной трассировки (backtrace) для чипов ESP
• as _ означает: "импортировать это, но не вводить в область видимости"
• Автоматически установит обработчик паники (panic handler) для отображения стека вызовов (backtraces) в случае паники

2. esp_println as _

• Импортирует и инициализирует функционал println с учетом специфики ESP
• as _ означает: "импортировать это, но не вводить в область видимости"
• Настраивает инфраструктуру лога для устройств ESP

Вместо использования:

use esp_backtrace;
use esp_println;

.. вы используете:

use {esp_backtrace as _, esp_println as _};

Это дает следующие выгоды:

1. Инициализация без загрязнения кода: крейты настраивают необходимую инфраструктуру без замусоривания вашего namespace
2. Side-effect import: импорт сам запустит код инициализации
3. Чистая область видимости: нет неиспользуемых имен в вашем коде

Включается обратная трассировка стека вызовов при панике:

use {esp_backtrace as _};

fn main() {
    let x = None.unwrap(); // Это вызовет panic
    // Но вы получите чистый backtrace вместо молчаливого падения
}

Можно использовать макрос println!:

use {esp_println as _};

fn main() {
    println!("Hello ESP!"); // работает через последовательный вывод
    println!("Temperature: {:.1}°C", 25.5);
}

Типовое использование в проектах ESP:

#![no_std]
#![no_main]

use {esp_backtrace as _, esp_println as _};

#[entry]
fn main() -> ! {
    println!("Старт системы...");

    // Код вашего приложения

    loop {}
}

Шаблон use {esp_backtrace as _, esp_println as _} важен для отладки (backtraces) и вывода в лог сообщений (println) проектов ESP, предоставляя важнейшие инструменты для поддержки чистоты и ясности кода.

use heapless::Vec;

Импортирует выделяемый в стеке вектор фиксированного размера из крейта heapless, что важно для модели no_std и разработки встраиваемых приложений.

heapless::Vec это версия Vec со следующими особенностями:

• Не использует выделение памяти из кучи (выделяемая память полностью находится в стеке)
• Вектор занимает фиксированный объем памяти (fixed capacity), определяемый во время компиляции
• Нет возможности динамического изменения объема выделения памяти - емкость вектора фиксирована
• Совместимость с моделью no_std - работает во встраиваемых системах

Ключевые отличия от std::Vec:

Синтаксис и использование:

use heapless::Vec;

// Создание массива Vec фиксированной емкости из 8 элементов
let mut vec: Vec< i32, 8> = Vec::new();

// Проталкивание в массив элементов (до своей емкости)
vec.push(1).unwrap();    // возвратит Result< (), ()>
vec.push(2).unwrap();
vec.push(3).unwrap();

// Доступ к элементам массива
println!("First: {}", vec[0]);

// Итерация по элементам массива
for item in &vec {
    println!("Item: {}", item);
}

Общепринятые шаблоны использования:

1. Буфер фиксированного размера

use heapless::Vec;

// Буфер для 16 результатов чтения датчика
let mut readings: Vec< f32, 16> = Vec::new();

for _ in 0..16 {
    let reading = read_sensor();
    readings.push(reading).unwrap(); // Произойдет паника, если буфер заполнится
}

2. Обработка ошибок

use heapless::Vec;

let mut vec: Vec< u8, 4> = Vec::new();

// Изящная обработка заполнения вектора
match vec.push(1) {
    Ok(()) => println!("Добавлено"),
    Err(_) => println!("Вектор заполнен!"),

3. Статическое хранилище

use heapless::Vec;
use core::mem::MaybeUninit;

// Предварительно выделенная память
static mut BUFFER: MaybeUninit< Vec< u8, 1024>> = MaybeUninit::uninit();

Почему используют heapless::Vec:

• Не требуется специальные функции выделения памяти (no allocator) - хорошо работает в bare-metal окружениях
• Предсказуемое использование памяти - нет фрагментации кучи
• Безопасность, проверяемая в момент компиляции - емкость известна в момент компиляции
• Минимальные затраты процессорного времени - нет задержек на выделение памяти

Недостатки (?): необходимо заранее указывать емкость выделяемой памяти. Например:

// ✅ корректное выделение - емкость указана
let mut v: Vec< i32, 10> = Vec::new();

// ❌ неправильно - не указана емкость
let mut v = Vec::new(); // ошибка: пропущена аннотация типа

Импорт heapless::Vec особенно важен для разработки встраиваемых приложений, когда выделение памяти в куче недоступно или нежелательно, однако все еще необходимо поведение, похожее на динамическое выделение памяти.

use embassy_sync::channel::Channel;

Импортирует тип Channel из библиотеки embassy-sync, что предоставляет примитивы синхронизации для async/await программирования встраиваемых систем.

• embassy_sync: субмодуль фреймворка Embassy для embedded async Rust
• channel::Channel: thread-safe сообщение, передаваемое по каналу. Разработано для кода синхронизации задач, работающих по принципу async/await.

// Обычно используется примерно так:
use embassy_sync::channel::Channel;

// Создается канал, который может содержать до 4 сообщений типа i32
static CHANNEL: Channel< embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex, \
    i32, 4> = Channel::new();

Назначение embassy_sync::channel::Channel:

• Коммуникация между задачами: пересылка данных между асинхронно выполняемыми задачами (async tasks)
• Thread-safe: безопасное использование между различными контекстами выполнения кода
• Async-aware: разработано для интеграции в функционал async/await
• Не используется выделение памяти в куче: подходит для встраиваемых систем

Общий пример использования:

// Задача, передающая данные
async fn producer(ch: &Channel< impl Mutex, i32, 4>) {
    ch.send(42).await;
}

// Задача, принимающая данные
async fn consumer(ch: &Channel< impl Mutex, i32, 4>) {
    let value = ch.receive().await;
    println!("Принято: {}", value);
}

Фреймворк Embassy популярен для разработки встраиваемых систем, где нужны эффективные примитивы async/await, не нуждающиеся в стандартной библиотеке или выделении памяти из кучи.

use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;

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

• embassy_sync: модуль синхронизации Embassy
• blocking_mutex: мьютекс, который выполняет блокировку место использования async/await
• raw: низкоуровневый интерфейс мьютекса
• CriticalSectionRawMutex: реализация мьютекса, которая использует для синхронизации критические секции кода

// Это "raw" мьютекс, который для защиты использует критические секции
pub struct CriticalSectionRawMutex;

Как это работает:

• Critical Sections: секция кода, в которой запрещены прерывания для обеспечения атомарности операций
• Blocking: задачи будут блокироваться (ждать) вместо того, чтобы уступать контекст в состоянии locked
• Zero-cost: нет runtime затрат, когда потерян контекст выполнения
• SMP-safe: безопасное использование на многоядерных системах (если это поддерживается)

Типовое использование:

use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::mutex::Mutex;

// Обертка общих данных в этом мьютексе
static SHARED_DATA: Mutex< CriticalSectionRawMutex, i32> = Mutex::new(0);

async fn task() {
    let mut data = SHARED_DATA.lock().await;
    *data += 1;
}

Когда и как это используется:

• Код, критичный ко времени выполнения: там, где необходима управляемая латентность прерываний
• Короткие критические секции: для защиты очень быстрых операций
• Многоядерные системы: когда вам нужен безопасный функционал SMP (symmetric multiprocessing)
• Предпочтительна блокировка: когда вам нужны задачи, которые выполняют блокирование (block) вместо уступки процессорного времени (yield)

Альтернативы в Embassy:

• NoopRawMutex - без синхронизации, одно ядро (single-core), одна задача (single-task)
• ThreadModeRawMutex - для single-core, multi-task (non-SMP)
• Другие raw мьютексы для различных аппаратных возможностей

Импорт embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex представляет часть гибкого функционала синхронизации фреймворка Embassy, который позволяет вам выбрать правильную стратегию блокировки в соответствии с требованиями встраиваемого приложения.

esp_bootloader_esp_idf::esp_app_desc!();

Это процедурный макрос, используемый в приложениях ESP-IDF (Espressif's IoT Development Framework). Он генерирует и инициализирует структуру описания приложения микроконтроллеров ESP (ESP32/ESP8266 и т. п). Это специальная структура данных, содержащая метаданные вашего firmware приложения:

• Версия приложения (major.minor.patch)
• Имя проекта
• Дата и время сборки (date, time)
• Версия IDF (ESP-IDF framework version)
• App ELF SHA256 (криптографический хэш вашего приложения)

Типовое использование:

esp_app_desc!();

Назначение:

• Идентификация загрузчика (bootloader) - помогает загрузчику проверять и обслуживать ваше приложение
• Обновления OTA - предоставляет информацию версии для обновления по радио (over-the-air, OTA: обычно это Wi-Fi)
• Отладка - помогает идентифицировать версию работающего firmware
• Безопасность - содержит хэш, позволяющий проверить целостность приложения

Этот макрос Rust эквивалентен макросу языка C:

ESP_APP_DESC_DEFAULT()

Генерируемая структура размещается в специальной секции .rodata_desc бинарного кода, размещение которой известно загрузчику ESP32.

Этот макрос важен для правильной работы приложения ESP32 и он обычно размещается в главном файле вашего приложения Rust ESP-IDF (обычно это файл main.rs).

[Ссылки]

1. Clippy site:doc.rust-lang.org.
2. Rust ESP32: руководство новичка.