Обновление до версии 0.3.0

- обновлен elbear_fw_bootloader - добавлена проверка контрольной суммы каждой строки hex файла.
- в модуль работы с АЦП добавлена функция analogReadResolution(). Функция analogRead() теперь возвращает усредненное по 10 измерениям значение.
- общая функция обработки прерываний перенесена в память RAM. Обработчики прерываний модулей External Interrupts и Advanced I/O (функция tone()) так же перенесены в память RAM для увеличения скорости выполнения кода.
- в пакет добавлены библиотеки EEPROM, Servo, SoftSerial, NeoPixel, MFRC522 адаптированные для работы с платой Elbear Ace-Uno.
- добавлено описание особенностей работы с пакетом

README.md

@@ -3,49 +3,93 @@
 
  
 ## Установка пакета в ArduinoIDE
-1. Установите [Arduino IDE](https://www.arduino.cc/en/software).
-2. Откройте меню `Файл -> Параметры`.
-3. Вставьте данную ссылку в поле "Дополнительные ссылки для Менеджера плат":  
-`https://elron.tech/files/package_elbear_beta_index.json`  
-![Add_board](docs/Add_board.PNG)
-4. Откройте меню `Инструменты -> Плата -> Менеджер плат...`.
-5. В поиске найдите плату `Elbear Ace-Uno`, выберите нужную версию и нажмите кнопку `Установить`.  
-![Install_board](docs/Install_board.PNG)
-6. Процесс установки может занять некоторое время. Результаты установки отобразятся в поле `Вывод`, а так же во всплывающих уведомлениях.  
-![Installation_process](docs/Installation_process.PNG)
+Для установки пакета в параметрах ArduinoIDE необходимо добавить ссылку `https://elron.tech/files/package_elbear_beta_index.json` в поле "Дополнительные ссылки для Менеджера плат".  
+Подробные шаги по установке и начальной настройке описаны в [инструкции](./Instructions.md).
 
-Для загрузки скетчей по USB в ArduinoIDE необходимо, чтобы на плату Elbear Ace-Uno была загружена специальная программа-загрузчик ([elbear_fw_bootloader](https://gitflic.ru/project/elron-tech/elbear_fw_bootloader)). Если она уже есть на плате, можно сразу переходить к работе. Если загрузчика еще нет или необходимо обновить его на плате, ниже описан процесс загрузки. Актуальная версия программы-загрузчика входит в состав пакета поддержки, отдельно скачивать её не нужно.
+## Функциональное назначение выводов  
+![Pinout](docs/pinout.PNG)
 
-Платы ревизии 1.1.0 готовы к использованию в ArduinoIDE из коробки, так как поставляются с предварительно загруженной программой-загрузчиком.
+## Особенности использования платы Elbear Ace-Uno в ArduinoIDE
+### Цифровые выводы
+На плате Elbear Ace-Uno доступны встроенные светодиод и кнопка. Для их использования необходимо воспользоваться макросами `LED_BUILTIN` и `BTN_BUILTIN`, передавая их в качестве аргументов функции вместо номера цифрового вывода. Макросу `LED_BUILTIN` соответствует номер вывода D22, а макросу `BTN_BUILTIN` - D23.  
+В отличие от стандартного функционала Arduino, на плате Elbear Ace-Uno невозможно управлять притяжками цифрового вывода, настроенного на вход, с помощью функции `void digitalWrite(uint32_t PinNumber, uint32_t Val)`. Для включения притяжки к питанию необходимо воспользоваться функцией `void pinMode(PinNumber, INPUT_PULLUP)`.  
+Для инвертирования состояния цифровых выводов доступна функция `void digitalToggle(uint32_t PinNumber)`.  
 
-## Загрузка программы-загрузчика через ArduinoIDE
-1. Подключите плату Elbear Ace-Uno к ПК через программатор ELJTAG.
-2. В ArduinoIDE выберите программатор: `Инструменты -> Программатор -> mik32 uploader`.
-3. Для загрузки программы-загрузчика выберите `Инструменты -> Записать Загрузчик`.  
-![Bootloader](docs/Bootloader.png)
-4. При возникновении проблем с загрузкой ознакомьтесь с разделом `Настройка программатора` в [инструкции](https://elron.tech/wp-content/uploads/2024/05/instrukcija-po-pervomu-zapusku.pdf) по первому запуску платы ELBEAR ACE-UNO.  
-Теперь можно загружать скетчи в плату по USB.
+### Аналоговые выводы
+#### АЦП 
+Встроенный в MIK32 АЦП обладает разрешением 12 бит, однако по умолчанию в Arduino IDE применяется разрешение 10 бит. С помощью функции `void analogReadResolution(uint8_t resolution)` можно изменять разрешение в диапазоне от 1 до 32 бит.  
+Функция `uint32_t analogRead(uint32_t PinNumber)` возвращает результаты измерения после усреднения по 10 значениям.  
+#### ШИМ  
+На плате Elbear Ace-Uno доступны следующие выводы для формирования ШИМ-сигнала: D3, D5, D6, D9, D10, D11. Генерация сигнала осуществляется с помощью 32-битного таймера. Выводы  D3, D5, D6, D9 подключены к таймеру 1, выводы D10, D11 подключены к таймеру 2. Выводы, подключенные к одному и тому же таймеру, выдают ШИМ-сигнал одинаковой частоты.  
+Цифровой вывод D10 не может быть использован для генерации ШИМ, если одновременно активен интерфейс SPI. Это ограничение связано с особенностями работы микроконтроллера. Ограничение не распространяется на использование D10 в качестве цифрового вывода при активном SPI.  
+По умолчанию частота сформированного ШИМ-сигнала составляет 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)`.
 
-## Начало работы
-1. Подключите плату к ПК по USB.
-2. Откройте ArduinoIDE и загрузите необходимый скетч. Для начала работы можно воспользоваться готовыми примерами, например - `Файл -> Примеры -> 01.Basics -> Blink`.  
-![Blink_example](docs/Blink_example.png)
-3. Выберите активную плату - `Инструменты -> Плата`.  
-![Set_board](docs/Set_board.png)
-4. Выберите используемый COM порт - `Инструменты -> Порт`.  
-![Set_port](docs/Set_port.png)  
-Выбранные плата и порт в ArduinoIDE должны отображаться следующим образом:  
-![Selected_board_port](docs/Selected_board_port.png)
-5. Проверьте скетч, нажав соответствующую кнопку.  
-![Build_project](docs/Build_project.png)
-6. Загрузите полученную прошивку на плату.  
-![Flash_project](docs/Flash_project.png)
-7. При необходимости можно открыть терминал и получать сообщения от платы по интерфейсу Serial. Для этого выберите `Инструменты -> Монитор порта`.  
-![Monitor](docs/Monitor.png)
+### Прерывания  
+На плате Elbear Ace-Uno доступно 7 прерываний, настраиваемых функцией `void attachInterrupt(uint8_t interruptNum, void (*userFunc)(void), int mode)`:  
+  
+|Цифровой вывод|Номер прерывания|
+|---------|---------|
+|D2|0|
+|D3|1|
+|D4|2|
+|D5|3|
+|D8|4|
+|D9|5|
+|`BTN_BUILTIN`|6|  
 
+Для получения номера прерывания по номеру вывода существует функция `int8_t digitalPinToInterrupt(uint32_t digPinNumber)`.  
+  
+В микроконтроллере MIK32 предусмотрен всего один вектор прерывания. Когда срабатывает прерывание от любого источника, общая функция-обработчик последовательно проверяет все возможные источники и, при необходимости, вызывает соответствующие обработчики конкретных модулей. Поэтому важно, чтобы функции, вызываемые при прерываниях, были небольшими и обеспечивали максимально быстрое завершение обработки. Это позволит избежать задержек и снизит риск пропуска последующих прерываний.  
+Общая функция-обработчик прерываний располагается в RAM памяти. Это позволяет устранить задержки, связанные с кэшированием при работе из FLASH памяти. Обработчики прерываний, назначаемые на цифровые выводы с помощью функции `void attachInterrupt(uint8_t interruptNum, void (*userFunc)(void), int mode)`, и обработчик прерывания для функции `tone()` так же располагаются в памяти RAM.  
+
+### Serial
+Для работы доступно два последовательных интерфейса. Нулевой интерфейс доступен на выводах D0, D1, для работы с ним используется экземпляр класса под названием `Serial`. Нулевой интерфейс используется для вывода информации в Монитор порта в Arduino IDE.  
+Первый интерфейс доступен на выводах D7, D8, используемый экземпляр класса - `Serial1`.  
+Доступны следующие настройки режима работы каждого интерфейса: длина данных - 7 или 8 бит; бит четности - нет, четный, нечетный; стоп бит - 1 или 2 бита.
+
+### Предупреждения об ошибках
+Если в скетче используется интерфейс `Serial`, при возникновении ошибок при использовании какой-либо функции из пакета в порт может передаваться сообщение об этой ошибке с пояснением. Например, если в функцию будет передан некорректный номер цифрового вывода, предупреждение об этом появится в подключенном com порту.  
+По умолчанию вывод предупреждений включен. Если интерфейс `Serial` используется для коммуникации с другим устройством, вывод предупреждений можно отключить. Для этого в самом начале функции `void setup()` необходимо вызвать макрос `DISABLE_ERROR_MESSAGES();`. Вывод предупреждений можно включить обратно, вызвав макрос `ENABLE_ERROR_MESSAGES();` в любом месте программы.
+
+### Библиотеки, входящие в состав пакета
+Входящие в состав пакета библиотеки используют периферию микроконтроллера MIK32 Амур и/или адаптированы для работы с ним.  
+  
+|Библиотека|Описание|Заметки|
+|---------|---------|------|
+|[SPI](https://docs.arduino.cc/language-reference/en/functions/communication/SPI/)|Библиотека для работы с интерфейсом SPI|Для работы используется встроенный SPI1. Доступные делители частоты - `SPI_CLOCK_DIV4`, `SPI_CLOCK_DIV8`, `SPI_CLOCK_DIV16`, `SPI_CLOCK_DIV32`, `SPI_CLOCK_DIV64`, `SPI_CLOCK_DIV128`, `SPI_CLOCK_DIV256`, обеспечивают частоту работы от 125 кГц до 8 МГц. Скорость работы по умолчанию - 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 сервоприводов|
+|[NeoPixel](https://docs.arduino.cc/libraries/adafruit-neopixel/)|Библиотека для работы с адресными светодиодами|Функция, выводящая состояние пикселей на цифровой вывод платы, перенесена в память RAM для корректной работы на MIK32 Амур|
+|[MFRC522](https://docs.arduino.cc/libraries/mfrc522/)|Библиотека для работы с RFID картами|Исправлен баг, вызывающий ошибку компиляции в новых компиляторах gcc|
+
+## Протестированные библиотеки
+|Библиотека|Описание|
+|---------|---------|
+|[RFID_MFRC522v2](https://docs.arduino.cc/libraries/rfid_mfrc522v2/)|Новая версия библиотеки MFRC522 для работы с RFID картами|
+|[SD](https://www.arduino.cc/en/Reference/SD)|Библиотека, позволяющая считывать и записывать информацию на SD карты|
+|[TimeLib](https://docs.arduino.cc/libraries/time/)|Библиотека для удобной работы с переменными времени|
+|[Ds1302](https://reference.arduino.cc/reference/en/libraries/ds1302/)|Библиотека для работы с микросхемой часов реального времени DS1302|
+|[DS1307RTC](https://docs.arduino.cc/libraries/ds1307rtc/)|Библиотека для работы с микросхемой часов реального времени DS1307|
+|[microDS3231](https://docs.arduino.cc/libraries/microds3231/)|Легкая библиотека для работы с микросхемой часов реального времени DS3231|
+|[Rtc](https://github.com/Makuna/Rtc/tree/master)|Библиотека для работы с разными микросхемами часов реального времени|
+|[AHT10](https://github.com/enjoyneering/AHT10/tree/master)|Библиотека для работы с датчиками температуры и влажности AHT10, AHT15, AHT20|
+|[DHT](https://docs.arduino.cc/libraries/dht-sensor-library/)|Библиотека для работы с датчиками температуры и влажности типа DHT|
+|[Adafruit_BMP280](https://docs.arduino.cc/libraries/adafruit-bmp280-library/)|Библиотека для работы с датчиками давления и высоты BMP280|
+|[MPU6050](https://reference.arduino.cc/reference/en/libraries/mpu6050/)|Библиотека для работы с акселерометром/гироскопом MPU6050|
+|[Kalman](https://docs.arduino.cc/libraries/kalman-filter-library/)|Библиотека, реализующая фильтр Калмана|
+|[LiquidCrystal_I2C](https://docs.arduino.cc/libraries/liquidcrystal-i2c/)|Библиотека для управления LCD дисплеями по интерфейсу I2C|
+|[JoystickShield](https://github.com/sudar/JoystickShield/tree/master)|Библиотека для работы с шилдом JoystickShield|
+|[RF24](https://docs.arduino.cc/libraries/rf24/)|Драйвер радиоустройств, библиотека для работы с микросхемами nRF24L01(+)|
+|[Bonezegei_ULN2003_Stepper](https://docs.arduino.cc/libraries/bonezegei_uln2003_stepper/)|Библиотека драйвера шагового двигателя, управляемого микросхемой ULN2003|
+|[Ethernet](https://docs.arduino.cc/libraries/ethernet/)|Библиотека, позволяющая использовать Ethernet шилд для подключения к Интернету|
 
-При возникновении вопросов или выявлении проблем можно оставить заявку [здесь](https://gitflic.ru/project/elron-tech/elbear_arduino_bsp/issue).
 
 # Полезные ссылки 
 *  [Материалы по платам ELBEAR ACE-UNO](https://elron.tech/support/#elbear)
 *  [Телеграмм-канал компании (обновления по проекту ELBEAR и другим)](https://t.me/elrontech)
+  
+При возникновении вопросов или выявлении проблем можно оставить заявку [здесь](https://gitflic.ru/project/elron-tech/elbear_arduino_bsp/issue).