# elbear_arduino_bsp
Пакет поддержки плат на базе микроконтроллера MIK32 Амур в среде программирования Arduino IDE.

 
## Установка пакета в ArduinoIDE и подготовка к работе
Для установки пакета в параметрах ArduinoIDE необходимо добавить ссылку `https://elron.tech/files/package_elbear_beta_index.json` в поле "Дополнительные ссылки для Менеджера плат".  
Подробные шаги по установке, начальной настройке и записи начального загрузчика для всех поддерживаемых плат описаны в [инструкции](./docs/Instructions.md).

## Платы, входящие в состав пакета
Пакет включает в себя поддержку следующих плат:
- [ELBEAR ACE-UNO](./docs/Elbear_description.md) 8 Mb / 16 Mb / 32 Mb  
- [ELBEAR ACE-NANO](./docs/nano_description.md)  
- [ELSOMIK](./docs/elsomik_description.md)  
- [START-MIK32](./docs/Start_mik32_description.md)  

## Особенности использования пакета в ArduinoIDE
### Цифровые выводы
В отличие от стандартного функционала Arduino на платах, входящих в состав пакета, невозможно управлять притяжками цифрового вывода, настроенного на вход, с помощью функции `void digitalWrite(uint32_t PinNumber, uint32_t Val)`. Для включения притяжки к питанию необходимо воспользоваться функцией `pinMode(PinNumber, INPUT_PULLUP)`.  
Доступна возможность конфигурирования цифрового вывода на вход с притяжкой к земле, для этого необходимо использовать макрос `INPUT_PULLDOWN` - `pinMode(PinNumber, INPUT_PULLDOWN)`.  
Для инвертирования состояния цифровых выводов доступна функция `void digitalToggle(uint32_t PinNumber)`.  

### Аналоговые выводы
#### АЦП 
Встроенный в MIK32 АЦП обладает разрешением 12 бит, однако по умолчанию в Arduino IDE применяется разрешение 10 бит. С помощью функции `void analogReadResolution(uint8_t resolution)` можно изменять разрешение в диапазоне от 1 до 32 бит.  
Функция `uint32_t analogRead(uint32_t PinNumber)` возвращает результаты измерения после усреднения по 10 значениям.  
Номера выводов, поддерживающих АЦП, отличаются для каждой платы и перечислены в их описаниях.
#### ШИМ  
По умолчанию частота сформированного ШИМ-сигнала составляет 1 кГц. Функция `void analogWriteFrequency(uint32_t freq)` позволяет изменить частоту сигнала в диапазоне от 1 Гц до 1 МГц.  
По умолчанию разрешение, используемое в функции `void analogWrite(uint32_t PinNumber, uint32_t writeVal)`, составляет 8 бит. Функция `void analogWriteResolution(uint8_t resolution)` позволяет измененить разрешение в диапазоне от 1 до 32 бит.  
Остановить генерацию ШИМ-сигнала можно, вызвав функцию `void analogWriteStop(uint32_t PinNumber)` или функции `void digitalWrite(uint32_t PinNumber, uint32_t Val)`/`int digitalRead(uint32_t PinNumber)`.  
Номера выводов, поддерживающих ШИМ, отличаются для каждой платы и перечислены в их описаниях.

### Прерывания  
Платы, входящих в состав пакета, позволяют использовать прерывания, настраиваемые функцией `void attachInterrupt(uint8_t interruptNum, void (*userFunc)(void), int mode)`. Номера выводов, поддерживающих прерывания, отличаются для каждой платы и перечислены в их описаниях.  
Для получения номера прерывания по номеру вывода существует функция `int8_t digitalPinToInterrupt(uint32_t digPinNumber)`.  
  
В микроконтроллере MIK32 предусмотрен всего один вектор прерывания. Когда срабатывает прерывание от любого источника, общая функция-обработчик последовательно проверяет все возможные источники и, при необходимости, вызывает соответствующие обработчики конкретных модулей. Поэтому важно, чтобы функции, вызываемые при прерываниях, были небольшими и обеспечивали максимально быстрое завершение обработки. Это позволит избежать задержек и снизит риск пропуска последующих прерываний.  
Общая функция-обработчик прерываний располагается в RAM памяти. Это позволяет устранить задержки, связанные с кэшированием при работе из FLASH памяти. Обработчики прерываний, назначаемые на цифровые выводы с помощью функции `void attachInterrupt(uint8_t interruptNum, void (*userFunc)(void), int mode)`, и обработчик прерывания для функции `tone()` так же располагаются в памяти RAM.  

Глобальное разрешение прерываний активируется после завершения функции `setup()`. Если необходимо использовать прерывания внутри самой функции `setup()`, их можно включить вручную, вызвав функцию `interrupts()` перед вызовом функций, работающих с прерываниями. Прерывания используются для приема данных модулями `Serial`, `Wire`, для работы библиотеки `Servo`, функцией `tone()`.
  
В пакете поддержки доступна возможность дополнения или замены стандартного обработчика прерываний пользовательской функцией-обработчиком. Для этого в своем скетче необходимо определить функцию `extern "C" bool ISR()`, она вызывается первой в стандартном обработчике. Внутри функции можно проверять флаги прерываний и реагировать на нужные. Важно очищать флаги обрабатываемых прерываний, чтобы обработчик работал корректно.  
Если функция возвращает `false`, после ее выполнения так же будет выполнен код стандартного обработчика прерываний. Если функция возвращает `true`, выполнение кода стандартного обработчика  будет пропущено.  
Пользовательскую функцию необходимо располагать в RAM памяти, так как стандартный обработчик прерываний расположен именно там.  
Ниже приведен пример пользовательского обработчика прерывания по переполнению от 16-битного таймера 1:  
```
extern "C" __attribute__((section(".ram_text"))) bool ISR(void)
{
    // обработка прерывания от 16-битного таймера 
    if (EPIC_CHECK_TIMER16_1())
        {
            if (TIM16_GET_ARRM_INT_STATUS(htimer16_1_))
            {
                // необходимые действия при переполнении таймера
            }
            // очистить флаги прерывания от таймера 1
            TIM16_CLEAR_INT_MASK(htimer16_1_, 0xFFFFFFFF);
        }
    return false;
}
```
Для корректной работы функции из примера необходимо подключить в скетче следующие файлы:
```
#include "mik32_hal_timer16.h"
#include "wiring_LL.h" 
```
### Serial
Для работы доступно два последовательных интерфейса. Нулевой интерфейс используется экземпляром класса `Serial`. Информации в Монитор порта в Arduino IDE поступает через него. Первый интерфейс используется экземпляром класса `Serial1`. Выводы, на которых доступны указанные интерфейсы, перечислены в описании отдельных плат.  
Доступны следующие макросы для настройки режима работы каждого интерфейса в функции `Serial.begin()`: `SERIAL_7N1`, `SERIAL_8N1`, `SERIAL_7N2`, `SERIAL_8N2`, `SERIAL_7E1`, `SERIAL_8E1`, `SERIAL_7E2`, `SERIAL_8E2`, `SERIAL_7O1`, `SERIAL_8O1`, `SERIAL_7O2`, `SERIAL_8O2`. Здесь длина данных - 7 или 8 бит; бит четности - нет(N), четный(E), нечетный(O); стоп бит - 1 или 2 бита.

### Переопределение функции main
В ArduinoIDE доступна возможность определить пользовательскую функцию `main()` в скетче. Для этого необходимо удалить из скетча функции `setup()` и `loop()` и определить свою функцию `int main(void){}`. Чтобы весь функционал пакета поддержки работал корректно, перед заходом в бесконечный цикл необходимо вызвать функцию `post_init()`, внутри которой глобально разрешаются прерывания. Пример переопределения представлен ниже.  
![main_redefine_example_.png](docs/main_redefine_example_.png)  

### Предупреждения об ошибках
Если в скетче используется интерфейс `Serial`, при возникновении ошибок при использовании какой-либо функции из пакета в порт может передаваться сообщение об этой ошибке с пояснением. Например, если в функцию будет передан некорректный номер цифрового вывода, предупреждение об этом появится в подключенном com порту.  
По умолчанию вывод предупреждений включен. Если интерфейс `Serial` используется для коммуникации с другим устройством, вывод предупреждений можно отключить. Для этого в самом начале функции `void setup()` необходимо вызвать макрос `DISABLE_ERROR_MESSAGES();`. Вывод предупреждений можно включить обратно, вызвав макрос `ENABLE_ERROR_MESSAGES();` в любом месте программы.

## Библиотеки, входящие в состав пакета
Входящие в состав пакета библиотеки используют периферию микроконтроллера MIK32 Амур и/или адаптированы для работы с ним.  
  
|Библиотека|Описание|Заметки|
|---------|---------|------|
|[SPI](https://docs.arduino.cc/language-reference/en/functions/communication/SPI/)|Библиотека для работы с интерфейсом SPI|Для работы доступно два экземпляра класса - SPI (используется аппаратный SPI1) и SPI1 (используется аппаратный SPI0). Выводы, на которых доступны интерфейсы, перечислены в описании каждой платы. Доступные делители частоты - `SPI_CLOCK_DIV2`, `SPI_CLOCK_DIV4`, `SPI_CLOCK_DIV8`, `SPI_CLOCK_DIV16`, `SPI_CLOCK_DIV32`, `SPI_CLOCK_DIV64`, `SPI_CLOCK_DIV128`, `SPI_CLOCK_DIV256`, обеспечивают частоту работы от 125 кГц до 16 МГц. Скорость работы по умолчанию - 4 МГц. Для задания режима и скорости работы рекомендуется использовать `SPISettings(uint32_t speedMaximum, uint8_t dataOrder, uint8_t dataMode)`, а не соответствующие отдельные функции|
|[Wire](https://docs.arduino.cc/language-reference/en/functions/communication/Wire/)|Библиотека для работы с интерфейсом I2C|Для работы используется встроенный I2C1. Доступные частоты работы интерфейса: 100 кГц (`WIRE_FREQ_100K`), 400 кГц (`WIRE_FREQ_400K`), 1000 кГц (`WIRE_FREQ_1000K`). Скорость работы по умолчанию - 100 кГц. В режиме работы в качестве ведомого устройства функции, заданные через `void onReceive( void (*)(int)` и `void onRequest( void (*)(void) )`, выполняются в прерывании|
|[SoftwareSerial](https://docs.arduino.cc/learn/built-in-libraries/software-serial/)|Библиотека, реализующая программный последовательный интерфейс.|Доступные скорости работы - от 300 до 57600 бод. Для отправки данных (TX) можно использовать любой цифровой вывод. Для приема данных (RX) можно использовать только выводы, поддерживающие прерывания. Обработчик прерывания и связанные с ним функции располагаются в памяти RAM|
|[EEPROM](https://docs.arduino.cc/learn/built-in-libraries/eeprom/)|Библиотека для работы с памятью EEPROM|Для использования доступно 1024 байта встроенной EEPROM памяти. Для корректной работы библиотеки обязательно вызывать функцию `void EEPROM.begin()` перед началом работы с памятью|
|[Servo](https://docs.arduino.cc/libraries/servo/)|Библиотека для работы с сервоприводом|Библиотека использует 16-битный таймер 2 и прерывания от него. Любой цифровой вывод подходит для управления сервоприводом. Одновременно можно использовать до 12 сервоприводов. Для работы библиотеки используется таймер timer16_2|
|[NeoPixel](https://docs.arduino.cc/libraries/adafruit-neopixel/)|Библиотека для работы с адресными светодиодами|Функция, выводящая состояние пикселей на цифровой вывод платы, перенесена в память RAM для корректной работы на MIK32 Амур|
|[MFRC522](https://docs.arduino.cc/libraries/mfrc522/)|Библиотека для работы с RFID картами|Исправлен баг, вызывающий ошибку компиляции в новых компиляторах gcc|
|[OneWire](https://docs.arduino.cc/libraries/onewire/)|Библиотека для работы с интерфейсом 1-Wire|В стандартную библиотеку добавлена поддержка микроконтроллера MIK32 Amur|
|[IRremote](https://docs.arduino.cc/libraries/irremote/)|Библиотека позволяет отправлять и принимать инфракрасные сигналы, используя определенный набор протоколов|В стандартную библиотеку добавлена поддержка микроконтроллера MIK32 Amur. При приеме данных используется прерывание таймера timer16_0, работает с любым цифровым выводом. Для отправки данных с помощью встроенного ШИМ для плат Elbear Ace-Uno используется вывод D3, для платы START-MIK32 - вывод P0_0|
|[FreeRTOS](https://docs.arduino.cc/libraries/freertos/)|Библиотека для работы с операционной системой реального времени FreeRTOS|В стандартную библиотеку добавлена поддержка микроконтроллера MIK32 Amur. Период системного тика составляет 10 мс и формируется с помощью машинного таймера SysTick|

## Протестированные библиотеки
Список библиотек, работа которых была протестирована на платах, входящих в состав пакета поддержки, доступен [здесь](./docs/tested_libs.md).
  
## Протестированные модули
Список модулей и шилдов, работа которых была протестирована на платах, входящих в состав пакета поддержки, доступен [здесь](./docs/tested_shields.md).

## Режим отладки
Для всех плат, входящих в состав пакета, доступен режим отладки скетча в Arduino IDE версии 2.3.4 на Windows 10 x64. Подготовка к работе в режиме отладки описана в [инструкции.](./docs/debug_description.md) Функция отладки является экспериментальной.

## Полезные ссылки 
*  [Проблемы и их решения при работе с пакетом в Arduino IDE](https://docs.elron.tech/arduino/available-ide/arduinoIDE-bsp/bsp-troubleshooting)
*  [Описание плат ELBEAR](https://docs.elron.tech/arduino/)
*  [Материалы по платам ELBEAR ACE-UNO](https://docs.elron.tech/arduino/elbear-ace-uno)
*  [Материалы по платам ELBEAR ACE-NANO](https://docs.elron.tech/arduino/elbear-ace-nano)
*  [Материалы по платам ELSOMIK](https://docs.elron.tech/som/)
*  [Материалы по плате START-MIK32](https://docs.mikron.ru/wiki/boards/start.html)
*  [Телеграмм-канал компании](https://t.me/elrontech)
  
При возникновении вопросов или выявлении проблем можно оставить заявку [здесь](https://gitflic.ru/project/elron-tech/elbear_arduino_bsp/issue).
